Subscriptions

Name: Subscriptions API
Brand: Subscriptions
Availability: InStock

★ 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.

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.

Install Jentic One Beta (Self-Hosted)

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 | sh

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 instance

Jentic 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

GET STARTED

Start building with Subscriptions API

Explore with Jentic

View OpenAPI Document

Jentic publishes the only available OpenAPI document for Subscriptions, keeping it validated and agent-ready.

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.

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 though 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.

Complementary

HubSpot Marketing Events Extension

Marketing events depend on subscription consent before triggering email outreach

Use Subscriptions to verify consent first; use the Marketing API when registering the event itself.

Complementary

HubSpot CRM Cards

CRM contact records carry the email address that the Subscriptions API operates on

Use the CRM extensions for record-page UI; use Subscriptions for the underlying consent state per email address.

Alternative

Mailchimp Marketing API

Mailchimp manages subscription status on lists for portfolios that do not use HubSpot

Pick Mailchimp when the company's email programme runs on Mailchimp lists; pick HubSpot Subscriptions when consent must live with the HubSpot CRM contact record.

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.