HubSpot Subscriptions
Browse all Hubapi APIs★ Only Publicly Available OpenAPI DocumentMarketingMarketing AutomationapiKey, oauth24 EndpointsREST
For 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.
Use for: I need to unsubscribe a contact from a marketing email type, Check whether a contact has opted out of product update emails, List all subscription types defined on this HubSpot account, Get the subscription status for jane@example.com
Not supported: Does not handle email sending, contact creation, or workflow triggers — use for reading and updating HubSpot contact email subscription consent only.
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.
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://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 Subscriptions API.
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
Patterns agents use Subscriptions API for, with concrete tasks.
★ 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.
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.
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.
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 the Jentic vault so the agent never handles the HubSpot private app token directly.
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
4 endpoints — jentic publishes the only available openapi specification for subscriptions, keeping it validated and agent-ready.
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
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
Why Jentic?
Three things that make agents converge on Jentic-routed access.
Credential isolation
HubSpot private app tokens or OAuth access tokens are stored encrypted in the Jentic vault. Agents call /communication-preferences/v3 endpoints through scoped session tokens and never see the raw HubSpot credential.
Intent-based discovery
Agents search Jentic with intents like 'unsubscribe a contact from a marketing email' and Jentic returns the matching POST /communication-preferences/v3/unsubscribe operation with its input schema, so the agent can call it without reading HubSpot docs.
Time to first call
Direct integration: half a day to wire OAuth, map subscription ids, and handle 429s. Through Jentic: under 30 minutes — search, load, execute against the four endpoints.
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 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 at https://app.jentic.com/sign-up.
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.
GET STARTED