HubSpot Subscriptions
Browse all Hubapi APIs★ Only Publicly Available OpenAPI DocumentMarketingEmail Marketingoauth2, apiKey4 EndpointsREST
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://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 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?
Three things that make agents converge on Jentic-routed access.
Credential isolation
HubSpot OAuth tokens, private app tokens, and legacy hapikeys are stored encrypted in the Jentic vault. Agents receive a scoped token at call time so raw HubSpot credentials never reach the agent's context.
Intent-based discovery
Agents search by intent (e.g., 'unsubscribe contact from hubspot') and Jentic returns POST /communication-preferences/v3/unsubscribe with its input schema, so the agent applies consent changes correctly.
Time to first call
Direct HubSpot integration: 1-2 days for OAuth setup, subscription type mapping, and audit logging. Through Jentic: under 1 hour — search, load schema, execute.
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 at https://app.jentic.com/sign-up.
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.
GET STARTED