canonical: https://jentic.com/apis/hubapi.com/hubspot-communication-preferences-api

# HubSpot Subscriptions

Jentic publishes the only available OpenAPI specification for HubSpot Subscriptions, keeping it validated and agent-ready. The HubSpot Communication Preferences API manages subscription types - the topics or brands that contacts can opt into or out of for marketing communications. It returns the subscription definitions for a portal, reads the current opt status for an email address, and applies subscribe or unsubscribe changes. It is the compliance-critical surface for honouring contact consent.

## For AI agents

Read and update HubSpot contact subscription preferences across email types so agents respect opt-in and opt-out states before sending marketing communications.

## Scope

Does not handle email sending, list segmentation, or contact creation - use for managing subscription opt status only.

## Capabilities

- List every subscription definition configured in the HubSpot portal
- Retrieve subscription opt status for any email address
- Subscribe an email address to one or more subscription types
- Unsubscribe an email address from specific subscription types
- Honour GDPR-style consent updates from external preference centres
- Reconcile contact preferences before triggering a marketing send

## Use cases

### Preference Centre Sync

Companies often run a custom preference centre on their own site that lets contacts pick which topics they want emails about. The sync writes those choices back to HubSpot using subscribe and unsubscribe so HubSpot's own send-time suppression honours the contact's stated preference. It avoids double-opt-in confusion and keeps a single source of truth for consent.

Example prompt: Subscribe email 'jane@example.com' to subscriptionId 12345 with legalBasis 'CONSENT_WITH_NOTICE'

### Pre-Send Consent Check

Before a marketing automation triggers a send, an agent or workflow checks the recipient's status for the relevant subscription type. If the contact is unsubscribed for that type, the send is skipped and a downstream system is notified. This protects both deliverability and GDPR/CAN-SPAM compliance.

Example prompt: Call GET /communication-preferences/v3/status/email/jane@example.com and return whether subscriptionId 12345 has status SUBSCRIBED

### Subscription Type Inventory

When onboarding a new portal or auditing email programme structure, teams need to see every subscription type configured in HubSpot. The definitions endpoint returns the full list, including the human-readable name, description, and active flag. Marketing ops uses this to consolidate redundant subscription types or align them across regions.

Example prompt: Call GET /communication-preferences/v3/definitions and return every active subscription type with its id, name, and description

### Agent-Driven Unsubscribe Honouring

An AI agent that processes inbound support emails uses Jentic to apply unsubscribe requests received via free-text. It searches for 'unsubscribe contact from hubspot', loads the schema, and posts to /communication-preferences/v3/unsubscribe so the request is honoured immediately rather than queued for a human.

Example prompt: Search Jentic for 'unsubscribe email from hubspot subscription', load the schema, and unsubscribe 'jane@example.com' from all marketing subscriptions

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /communication-preferences/v3/definitions | List subscription type definitions |
| GET | /communication-preferences/v3/status/email/{emailAddress} | Get subscription status for an email address |
| POST | /communication-preferences/v3/subscribe | Subscribe an email address to a subscription type |
| POST | /communication-preferences/v3/unsubscribe | Unsubscribe an email address from a subscription type |

## Key resources

- **Definitions** — List the subscription types configured in the portal
- **Status** — Read the per-subscription opt status for an email address
- **Subscribe** — Opt an email address into one or more subscription types
- **Unsubscribe** — Opt an email address out of one or more subscription types

## Why Jentic

- **Setup:** Wiring the HubSpot Subscriptions API by hand means handling both OAuth and app-token auth against api.hubapi.com and getting the opt-in and opt-out payloads right yourself. Through Jentic you install once, import Subscriptions from the API Directory, store the credential once, and your agent calls it.
- **Permission scoping:** The subscribe and unsubscribe operations carry the contact and subscription in the request body, so limit the agent to the operations it needs, such as reading subscription status or subscribing a contact. You choose that set, so unsubscribing with POST /communication-preferences/v3/unsubscribe is not included unless you add it.
- **Credential handling:** Your HubSpot credential is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'unsubscribe a contact from a hubspot email', and Jentic returns POST /communication-preferences/v3/unsubscribe with its input schema so the agent applies the consent change without browsing the reference docs.

## Related APIs

- **HubSpot Marketing Events Extension** — Marketing events depend on subscription consent before triggering email outreach
- **HubSpot CRM Cards** — CRM contact records carry the email address that the Subscriptions API operates on
- **Mailchimp Marketing API** — Mailchimp manages subscription status on lists for portfolios that do not use HubSpot

## FAQ

### Why is there no official OpenAPI spec for HubSpot Subscriptions?

HubSpot does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call HubSpot Subscriptions via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the HubSpot Subscriptions API use?

It accepts OAuth 2.0 access tokens, the private-app-legacy header for private apps, and the hapikey query parameter as a legacy fallback. Jentic stores all of these in its encrypted vault and provides agents with a scoped token at execution time.

### Can I subscribe contacts to subscription types they previously opted out of?

Yes, but the subscribe request must include a legalBasis value such as CONSENT_WITH_NOTICE or LEGITIMATE_INTEREST_CLIENT, and HubSpot records the new opt-in event with timestamp and source. This preserves the audit trail required by GDPR and similar regulations.

### What are the rate limits for the HubSpot Subscriptions API?

HubSpot's standard public app limits apply: 100 requests per 10 seconds per private app token and 110 per 10 seconds per OAuth app per portal. For batch unsubscribe processing, throttle the calls or use the contact merge/import flows for bulk volumes.

### How do I unsubscribe a contact from all marketing emails through Jentic?

Search Jentic for 'unsubscribe email from hubspot', load the schema for POST /communication-preferences/v3/unsubscribe, and execute with the email address and the subscriptionId for the marketing subscription type. Repeat or batch for multiple types.

### Is the HubSpot Subscriptions API free?

API access is included with any HubSpot subscription that has Marketing Hub features. Subscription type configuration itself requires Marketing Hub Starter or higher; the API surfaces whatever is configured in the portal.

### Can I limit what my agent is allowed to do with the HubSpot Subscriptions API?

Yes. Because you run Jentic One yourself, your own rules decide which of the Subscriptions operations the agent may call and which credential it uses. You can allow only the reads it needs, such as listing subscription definitions or checking status for an email address, and leave out the write operations. For example, POST /communication-preferences/v3/unsubscribe is not available to the agent unless you add it to the set you approve.