Subscriptions

Name: Subscriptions API
Brand: Subscriptions
Availability: InStock

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

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

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

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

Complementary

HubSpot Communication Preferences API

Broader HubSpot communication preferences endpoints from the same portal

Choose this when you need preference operations beyond the four subscriptions endpoints

Complementary

HubSpot Marketing API

Send marketing emails to contacts whose consent state you have just verified

Use after Subscriptions to actually deliver email to opted-in contacts

Alternative

Mailchimp Marketing API

Mailchimp manages list subscription state and consent in its own audience model

Choose Mailchimp when the source of truth for marketing email is Mailchimp rather than HubSpot

Complementary

SendGrid Email Activity

SendGrid surfaces unsubscribe and bounce events that you can mirror back into HubSpot

Use when your transactional sender is SendGrid and you need to propagate opt-outs into HubSpot Subscriptions

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.