canonical: https://jentic.com/apis/hubapi.com/hubspot-subscriptions

# HubSpot Subscriptions

Jentic publishes the only available OpenAPI specification for Subscriptions, keeping it validated and agent-ready. The HubSpot Subscriptions API lets contacts control which forms of communication they receive from a HubSpot account, scoped to specific topics, brands, or the whole portal. Agents can list subscription definitions, read a contact's subscription status by email, and subscribe or unsubscribe contacts to keep marketing consent state in sync with external preference centres. The four endpoints under /communication-preferences/v3 cover the full read and update flow for contact-level consent.

## For AI agents

Read and update HubSpot contact email subscription preferences across defined subscription types. Use it to honour opt-ins, opt-outs, and consent state for marketing communications.

## Scope

Does not handle email sending, contact creation, or workflow triggers - use for reading and updating HubSpot contact email subscription consent only.

## Capabilities

- List the subscription definitions configured on a HubSpot account
- Look up the subscription status for every type for a given email address
- Subscribe a contact to a specific subscription definition with a legal basis
- Unsubscribe a contact from one subscription type without affecting others
- Sync external preference-centre opt-out events back into HubSpot consent records
- Audit a contact's communication preferences before sending marketing email

## Use cases

### Honour an unsubscribe from an external preference centre

When a contact opts out of marketing email through a hosted preference centre, the change has to flow back into HubSpot so that subsequent campaigns respect consent. POST /communication-preferences/v3/unsubscribe takes an email address and a subscription definition id and removes that consent without touching other subscription types. The call writes a HubSpot-native opt-out so downstream marketing emails skip the contact.

Example prompt: Call POST /communication-preferences/v3/unsubscribe with emailAddress=jane@example.com and the newsletter subscriptionId, then verify the change with GET /communication-preferences/v3/status/email/jane@example.com

### Audit consent before sending a campaign

Before triggering a marketing send to a list, an agent can verify each contact's current subscription state by email. GET /communication-preferences/v3/status/email/{emailAddress} returns every subscription definition with the current status and the legal basis. This prevents sending to contacts who have opted out or whose consent is missing.

Example prompt: Call GET /communication-preferences/v3/status/email/jane@example.com and return the list of subscriptionId values where status equals SUBSCRIBED

### Bootstrap subscription definitions in a new tool

When connecting a new tool to HubSpot, the agent needs the canonical list of subscription definitions configured in the portal. GET /communication-preferences/v3/definitions returns each definition with its id, name, and description so the integration can map external preference toggles to HubSpot subscription types.

Example prompt: Call GET /communication-preferences/v3/definitions and store id, name, and description for each definition for later mapping

### Agent-driven consent updates via Jentic

An AI agent processing customer service requests can update marketing consent inline. Through Jentic the agent searches for the unsubscribe operation, loads the schema, and executes it with the contact email and subscription id without leaving the conversation. Credentials stay in your Jentic One instance so the agent never handles the HubSpot private app token directly.

Example prompt: Search Jentic for 'unsubscribe a contact from a marketing email subscription', load the schema for POST /communication-preferences/v3/unsubscribe, and execute with the contact email and the subscription id supplied by the user

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /communication-preferences/v3/definitions | List subscription definitions on the account |
| GET | /communication-preferences/v3/status/email/{emailAddress} | Get subscription statuses for a contact by email |
| POST | /communication-preferences/v3/subscribe | Subscribe a contact to a subscription definition |
| POST | /communication-preferences/v3/unsubscribe | Unsubscribe a contact from a subscription definition |

## Key resources

- **Definitions** — Read the list of subscription definitions configured on the HubSpot account
- **Status** — Read a contact's subscription status across all definitions by email address
- **Subscribe** — Subscribe a contact to a specific subscription definition
- **Unsubscribe** — Unsubscribe a contact from a specific subscription definition

## Why Jentic

- **Setup:** Wiring the HubSpot Subscriptions API by hand means handling both app-token and OAuth auth against api.hubapi.com and getting the consent 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 marketing 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 Communication Preferences API** — Broader HubSpot communication preferences endpoints from the same portal
- **HubSpot Marketing API** — Send marketing emails to contacts whose consent state you have just verified
- **Mailchimp Marketing API** — Mailchimp manages list subscription state and consent in its own audience model
- **SendGrid Email Activity** — SendGrid surfaces unsubscribe and bounce events that you can mirror back into HubSpot

## FAQ

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

HubSpot does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call 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?

The spec lists three schemes: a private app token in the private-app-legacy header, an OAuth 2.0 access token, and a legacy hapikey query parameter. Private app tokens and OAuth are the supported routes today. Through Jentic the credential is stored encrypted in the vault and the agent receives only a scoped session token.

### Can I unsubscribe a contact from a single subscription type with the Subscriptions API?

Yes. POST /communication-preferences/v3/unsubscribe accepts an email address and a single subscriptionId, so you remove consent for that specific subscription definition without changing any other subscriptions on the contact.

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

The spec does not declare a per-endpoint limit. The HubSpot Subscriptions API is subject to the standard HubSpot account rate limits, which are 100 requests per 10 seconds for OAuth and private apps on most tiers. Check the daily usage with the Account Info API to stay under the daily call cap.

### How do I read a contact's subscription state through Jentic?

Search Jentic for 'get subscription status for an email address', load the schema for GET /communication-preferences/v3/status/email/{emailAddress}, then execute with the contact email. Jentic returns the JSON response with each subscription definition and its current status.

### Is the HubSpot Subscriptions API free?

The Subscriptions API is included with any HubSpot account that has Marketing Hub. There is no per-call charge from HubSpot, but every call counts against the account's daily and burst rate limits.

### 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 four subscription operations the agent may call, so you can allow read-only access like GET /communication-preferences/v3/definitions and GET /communication-preferences/v3/status/email/{emailAddress} while withholding the ability to change consent. If you want the agent to act, you can add POST /communication-preferences/v3/subscribe on its own and keep POST /communication-preferences/v3/unsubscribe out of scope, since unsubscribing is only available to the agent when you include it. The contact email and subscription id travel in the request body, so the agent can only touch consent for the operations and credentials you have granted it.