HubSpot Subscriptions

Name: Subscriptions API
Brand: Subscriptions
Availability: InStock

★ Only Publicly Available OpenAPI DocumentMarketingMarketing AutomationapiKey, oauth24 EndpointsREST

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.

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

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

GET STARTED

Start building with Subscriptions API

Explore with Jentic

View OpenAPI Document

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.

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 your Jentic One instance 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

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

Time to first call

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 with Jentic One, the self-hosted execution layer.

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.

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 four subscription operations the agent may call, so you can allow read-only access like GET /communication-preferences/v3/definitions and GET /communication-preferences/v3/status/email/{emailAddress} while withholding the ability to change consent. If you want the agent to act, you can add POST /communication-preferences/v3/subscribe on its own and keep POST /communication-preferences/v3/unsubscribe out of scope, since unsubscribing is only available to the agent when you include it. The contact email and subscription id travel in the request body, so the agent can only touch consent for the operations and credentials you have granted it.

HubSpot Subscriptions

Connect the Subscriptions to your agent

Capabilities

Start building with Subscriptions API

Use Cases

Key Endpoints

Why Jentic?

Related APIs

FAQs