HubSpot Subscriptions
Browse all Hubapi APIsAgent-ready OpenAPI document · curated by JenticMarketingEmail Marketingoauth2, apiKey4 EndpointsREST
Know of an official OpenAPI document? Contribute it →
For Agents
Read and update HubSpot contact subscription preferences across email types so agents respect opt-in and opt-out states before sending marketing communications.
Use for: I need to unsubscribe an email address from the newsletter, Get the current subscription status for a contact, List all subscription types configured in our HubSpot portal, Subscribe a contact to product update emails
Not supported: Does not handle email sending, list segmentation, or contact creation - use for managing subscription opt status only.
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.
Install Jentic One Beta
Connect the Subscriptions to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the 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%2Fhubapi.com%2Fhubspot-communication-preferences-api" | 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%2Fhubapi.com%2Fhubspot-communication-preferences-api" | 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 Subscriptions API.
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
Patterns agents use Subscriptions API for, with concrete tasks.
★ 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.
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.
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.
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.
Search Jentic for 'unsubscribe email from hubspot subscription', load the schema, and unsubscribe 'jane@example.com' from all marketing subscriptions
Key Endpoints
4 endpoints — jentic publishes the only available openapi specification for hubspot subscriptions, keeping it validated and agent-ready.
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
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
Why Jentic?
What agents get from Jentic-routed access to this vendor.
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 isolation
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.
Intent-based discovery
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
Alternatives and complements available in the Jentic catalogue.
FAQs
Specific to using Subscriptions API through Jentic.
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.
GET STARTED