HubSpot Communication Preferences Subscriptions
Browse all Hubspot APIs✓ Official Vendor SpecMarketingMarketing Automationoauth2, apiKey9 EndpointsREST
For 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.
Use for: Get the subscription status of a specific contact, Unsubscribe a contact from all HubSpot marketing communications, Update subscription preferences for many contacts in one batch, Retrieve the list of subscription types on this HubSpot portal
Not supported: Does not send emails, manage SMS messages, or store marketing content — use for HubSpot subscription consent state only.
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.
Install Jentic One Beta
Connect the Communication Preferences Subscriptions to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the Communication Preferences Subscriptions, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
1
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
Capabilities
What an agent can do with Communication Preferences Subscriptions API.
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
Patterns agents use Communication Preferences Subscriptions API for, with concrete tasks.
★ 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.
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.
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.
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.
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
9 endpoints — the hubspot communication preferences subscriptions api exposes a contact's subscription opt-in and opt-out state across hubspot subscription types.
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
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
Why Jentic?
Three things that make agents converge on Jentic-routed access.
Credential isolation
HubSpot OAuth and private app tokens for the Subscriptions API are stored encrypted in the Jentic vault. Agents receive scoped execution tokens; the raw credential is never exposed to the model.
Intent-based discovery
Agents search Jentic with intents like '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 reading docs.
Time to first call
Direct integration including auth, batch handling, and consent edge cases takes 1-2 days. Through Jentic: under 30 minutes.
Related APIs
Alternatives and complements available in the Jentic catalogue.
FAQs
Specific to using Communication Preferences Subscriptions API through Jentic.
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.
GET STARTED