HubSpot Communication Preferences Subscriptions
Browse all Hubspot APIs45
AI ReadinessFoundational (D)45/100
Official vendor OpenAPI document · agent-readyMarketingMarketing 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://jentic.com/install.sh?src=apis&api=%2Fapis%2Fhubspot.com%2Fhubspot-communication-preferences-subscriptions" | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fhubspot.com%2Fhubspot-communication-preferences-subscriptions" | 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
Jentic AI Readiness Score
This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.
C
Communication Preferences Subscriptions
- Foundational (D)45/100
73
Foundational Compliance63
Developer Experience & Jentic Compatibility20
AI-Readiness & Agent Experience94
Agent Usability70
Security78
AI DiscoverabilityPowered by JenticScoring Framework 1.0.0 | Scoring Engine 0.4.0
Show dimension breakdown
73
Foundational Compliance
Base layer of spec validity and structural soundness.
Grade: A-Signals: 4
94%
Lint Results
Aggregated quality score from linter diagnostics, weighted by severity.
100%
Resolution Completeness
Percentage of `$ref` references that resolve successfully.
0%
Specification Validity
Checks whether the API description parses successfully and conforms to its declared specification (e.g., OpenAPI).
100%
Structural Integrity
Structural correctness score based on schema issues using logarithmic dampening.
63
Developer Experience & Jentic Compatibility
Clarity, completeness, and ingestion readiness for developers and tooling.
Grade: BSignals: 4
2%
Example Density
How richly the API is illustrated with examples.
100%
Example Validity
Percentage of examples that conform to their schemas.
50%
Response Coverage
Percentage of operations with complete response definitions (success, client error, server error).
100%
Tooling Readiness
Health of API ingestion, bundling, and resolution within Jentic pipelines.
20
AI-Readiness & Agent Experience
Semantic breadth, depth, and agent comprehension for AI systems.
Grade: FSignals: 4
23%
Description Coverage
Coverage of descriptions across API elements.
0%
Error Standardization
Coverage of RFC 9457 Problem Details for error responses.
0%
OperationId Quality
Coverage, uniqueness, and casing consistency of operationIds for AI inference.
56%
Summary Coverage
Coverage of summaries across operations/tags/info.
94
Agent Usability
Functional utility, complexity comfort, and AI orchestration readiness.
Grade: A+Signals: 1
94%
Complexity Comfort
Agent comfort level based on API operational and structural complexity.
70
Security
Trust, risk posture, and security compliance.
Grade: A-Signals: 1
70%
Authentication Strength
Average quality of security schemes based on authentication method strength (weakest link for OAuth2).
78
AI Discoverability
Findability, semantic richness, and reasoning readiness.
Grade: A-Signals: 1
78%
Descriptive Richness
Clarity and depth of descriptions across API elements.
Score it yourself
Every API in the directory is allowlisted, so you can re-score it with no key required.
npx @jentic/api-scorecard-cli score <openapi-url>Why Jentic?
What agents get from Jentic-routed access to this vendor.
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 isolation
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.
Intent-based discovery
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
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.
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.
GET STARTED