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

# HubSpot Communication Preferences Subscriptions

The HubSpot Communication Preferences Subscriptions API exposes a contact's subscription opt-in and opt-out state across HubSpot subscription types. It supports retrieving a contact's preferences, updating individual subscriptions, unsubscribing from all communications, and running batch reads and writes for many contacts at once. Subscription type definitions can also be listed, making this the right surface for compliance with consent-driven marketing such as GDPR and CAN-SPAM.

## For AI agents

Read and update a HubSpot contact's email and communication subscription preferences, including unsubscribe-all flows and batch updates. Useful for agents handling consent and compliance.

## Scope

Does not send emails, manage SMS messages, or store marketing content - use for HubSpot subscription consent state only.

## Capabilities

- Retrieve subscription preferences for a single contact by email or ID
- Update a contact's status on a specific subscription type
- Unsubscribe a contact from every subscription in one call
- Batch read subscription statuses for many contacts at once
- Batch update subscription statuses across many contacts
- List all subscription type definitions available on the portal
- Identify contacts who have globally opted out of all communications

## Use cases

### GDPR Consent Management

Capture and update contact consent state in HubSpot when a user changes preferences in an external portal or mobile app. The Subscriptions API supports per-subscription updates and unsubscribe-all, making it possible to mirror consent decisions back to HubSpot in real time. Suitable for compliance with GDPR, CASL, and similar consent-based regimes.

Example prompt: POST /communication-preferences/v4/statuses/{subscriberIdString} with the subscription ID and status `OPT_OUT` when the user toggles off a newsletter in the external portal.

### Bulk Unsubscribe Reconciliation

After a deliverability event or list cleanup, batch-unsubscribe a list of contacts and reconcile their states with an external CRM. The batch endpoints minimise request volume and let an agent process thousands of contacts in a few calls, with a paired batch read to confirm the new state.

Example prompt: POST /communication-preferences/v4/statuses/batch/unsubscribe-all with a list of contact emails, then POST /communication-preferences/v4/statuses/batch/read to confirm the new status.

### Subscription Type Audit

Build an audit dashboard that shows which HubSpot subscription types exist on a portal and how many contacts are opted in to each. The definitions endpoint returns the canonical list of subscription types, and batch reads return per-contact statuses for aggregation.

Example prompt: GET /communication-preferences/v4/definitions to fetch all subscription types, then iterate batch reads to compute opt-in counts per type.

### Agent-Driven Preference Centre

Power a chat- or voice-driven preference centre with an AI agent that updates HubSpot subscription state on behalf of the contact. Through Jentic, the agent calls the right Subscriptions endpoint without bespoke HubSpot SDK code, and the HubSpot token stays out of the model's context.

Example prompt: Use Jentic search 'unsubscribe a contact from all HubSpot communications', load the schema for POST /communication-preferences/v4/statuses/{subscriberIdString}/unsubscribe-all, and execute with the contact's email.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /communication-preferences/v4/definitions | List all subscription type definitions |
| GET | /communication-preferences/v4/statuses/{subscriberIdString} | Get subscription preferences for a contact |
| POST | /communication-preferences/v4/statuses/{subscriberIdString} | Update a contact's subscription status |
| POST | /communication-preferences/v4/statuses/{subscriberIdString}/unsubscribe-all | Unsubscribe a contact from all subscriptions |
| POST | /communication-preferences/v4/statuses/batch/read | Batch retrieve subscription statuses |
| POST | /communication-preferences/v4/statuses/batch/write | Batch update subscription status |
| POST | /communication-preferences/v4/statuses/batch/unsubscribe-all | Batch unsubscribe contacts |

## Key resources

- **Subscription statuses** — Per-contact subscription state under /communication-preferences/v4/statuses.
- **Subscription definitions** — Portal-wide subscription type metadata under /communication-preferences/v4/definitions.

## Why Jentic

- **Setup:** Wiring HubSpot Communication Preferences by hand means learning its OAuth2 access token or private app token auth, targeting the api.hubapi.com host, and handling batch read and write calls yourself. Through Jentic you install once, import HubSpot Communication Preferences from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** The Subscriptions API puts the subscriber id in the URL path (/communication-preferences/v4/statuses/{subscriberIdString}), so a rule can pin your agent to reading and setting status for one subscriber. You choose the operations it may call, so unsubscribe-all and the batch write operations are not included unless you add them.
- **Credential handling:** Your HubSpot access token or private app token 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' or 'list subscription types', and Jentic returns the matching Subscriptions operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **HubSpot CRM Contacts** — Look up the contact records whose subscription state is being managed.
- **HubSpot CRM Email Engagements** — Log and inspect individual email engagements alongside subscription state.
- **HubSpot CRM Lists** — Build and inspect lists driven by subscription status.

## FAQ

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

OAuth 2.0 authorization code flow or a private app token in the `private-app` header. Through Jentic, the credential lives in the encrypted vault and the agent receives a scoped execution token only.

### Can I unsubscribe a contact from every HubSpot subscription in one call?

Yes. POST /communication-preferences/v4/statuses/{subscriberIdString}/unsubscribe-all flips the contact's global opt-out flag, which suppresses every marketing subscription type on the portal in a single request.

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

Standard HubSpot API limits - about 100 requests per 10 seconds per OAuth app and daily caps on most paid tiers. Use the batch read and batch write endpoints to stay well below the per-request ceiling.

### How do I update a contact's preferences through Jentic?

Search Jentic with `update a HubSpot subscription preference`, load the schema for POST /communication-preferences/v4/statuses/{subscriberIdString}, and execute with the contact email and subscriptionId. Install with `pip install jentic` and authenticate via `JENTIC_AGENT_API_KEY`.

### Does this API let me list every subscription type on the portal?

Yes. GET /communication-preferences/v4/definitions returns all subscription type definitions, including IDs and friendly names, so an agent can resolve names to IDs before updating a contact's status.

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

Yes. Because Jentic One is self-hosted, you decide which of this API's operations your agent may call and which HubSpot credentials it uses. Since the subscriber id sits in the URL path at /communication-preferences/v4/statuses/{subscriberIdString}, your own rules can pin the agent to reading and setting status for a single subscriber. Higher-impact operations such as unsubscribe-all and the batch write endpoints are excluded until you explicitly add them.