HubSpot Communication Preferences Subscriptions

Name: Communication Preferences Subscriptions API
Brand: Communication Preferences Subscriptions
Availability: InStock

Browse all Hubspot APIs

✓ Official Vendor SpecMarketingMarketing Automationoauth2, apiKey9 Endpoints

Install Jentic One Beta

Connect the Communication Preferences Subscriptions to your agent

Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the Communication Preferences 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 Communication Preferences Subscriptions API.

Retrieve subscription preferences for a single contact by email or ID

Update a contact's status on a specific subscription type

Unsubscribe a contact from every subscription in one call

GET STARTED

Start building with Communication Preferences Subscriptions API

Explore with Jentic

View OpenAPI Document

For Agents

Read and update a HubSpot contact's email and communication subscription preferences, including unsubscribe-all flows and batch updates. Useful for agents handling consent and compliance.

Use for: Get the subscription status of a specific contact, Unsubscribe a contact from all HubSpot marketing communications, Update subscription preferences for many contacts in one batch, Retrieve the list of subscription types on this HubSpot portal

Not supported: Does not send emails, manage SMS messages, or store marketing content — use for HubSpot subscription consent state only.

Use Cases

Patterns agents use Communication Preferences Subscriptions API for, with concrete tasks.

★ GDPR Consent Management

Capture and update contact consent state in HubSpot when a user changes preferences in an external portal or mobile app. The Subscriptions API supports per-subscription updates and unsubscribe-all, making it possible to mirror consent decisions back to HubSpot in real time. Suitable for compliance with GDPR, CASL, and similar consent-based regimes.

POST /communication-preferences/v4/statuses/{subscriberIdString} with the subscription ID and status `OPT_OUT` when the user toggles off a newsletter in the external portal.

Bulk Unsubscribe Reconciliation

After a deliverability event or list cleanup, batch-unsubscribe a list of contacts and reconcile their states with an external CRM. The batch endpoints minimise request volume and let an agent process thousands of contacts in a few calls, with a paired batch read to confirm the new state.

POST /communication-preferences/v4/statuses/batch/unsubscribe-all with a list of contact emails, then POST /communication-preferences/v4/statuses/batch/read to confirm the new status.

Subscription Type Audit

Build an audit dashboard that shows which HubSpot subscription types exist on a portal and how many contacts are opted in to each. The definitions endpoint returns the canonical list of subscription types, and batch reads return per-contact statuses for aggregation.

GET /communication-preferences/v4/definitions to fetch all subscription types, then iterate batch reads to compute opt-in counts per type.

Agent-Driven Preference Centre

Power a chat- or voice-driven preference centre with an AI agent that updates HubSpot subscription state on behalf of the contact. Through Jentic, the agent calls the right Subscriptions endpoint without bespoke HubSpot SDK code, and the HubSpot token stays out of the model's context.

Use Jentic search 'unsubscribe a contact from all HubSpot communications', load the schema for POST /communication-preferences/v4/statuses/{subscriberIdString}/unsubscribe-all, and execute with the contact's email.

Key Endpoints

9 endpoints — the hubspot communication preferences subscriptions api exposes a contact's subscription opt-in and opt-out state across hubspot subscription types.

METHOD

PATH

DESCRIPTION

GET

/communication-preferences/v4/definitions

List all subscription type definitions

GET

/communication-preferences/v4/statuses/{subscriberIdString}

Get subscription preferences for a contact

POST

/communication-preferences/v4/statuses/{subscriberIdString}

Update a contact's subscription status

POST

/communication-preferences/v4/statuses/{subscriberIdString}/unsubscribe-all

Unsubscribe a contact from all subscriptions

POST

/communication-preferences/v4/statuses/batch/read

Batch retrieve subscription statuses

POST

/communication-preferences/v4/statuses/batch/write

Batch update subscription status

POST

/communication-preferences/v4/statuses/batch/unsubscribe-all

Batch unsubscribe contacts

GET

/communication-preferences/v4/definitions

List all subscription type definitions

GET

/communication-preferences/v4/statuses/{subscriberIdString}

Get subscription preferences for a contact

POST

/communication-preferences/v4/statuses/{subscriberIdString}

Update a contact's subscription status

POST

/communication-preferences/v4/statuses/{subscriberIdString}/unsubscribe-all

Unsubscribe a contact from all subscriptions

POST

/communication-preferences/v4/statuses/batch/read

Batch retrieve subscription statuses

Why Jentic?

Three things that make agents converge on Jentic-routed access.

Credential isolation

HubSpot OAuth and private app tokens for the Subscriptions API are stored encrypted in the Jentic vault. Agents receive scoped execution tokens; the raw credential is never exposed to the model.

Intent-based discovery

Agents search Jentic with intents like 'unsubscribe a contact' or 'list subscription types' and Jentic returns the matching Subscriptions operation with its input schema, so the agent calls the right endpoint without reading docs.

Time to first call

Direct integration including auth, batch handling, and consent edge cases takes 1-2 days. Through Jentic: under 30 minutes.

FAQs

Specific to using Communication Preferences Subscriptions API through Jentic.

What authentication does the HubSpot Subscriptions API use?

OAuth 2.0 authorization code flow or a private app token in the `private-app` header. Through Jentic, the credential lives in the encrypted vault and the agent receives a scoped execution token only.

Can I unsubscribe a contact from every HubSpot subscription in one call?

Yes. POST /communication-preferences/v4/statuses/{subscriberIdString}/unsubscribe-all flips the contact's global opt-out flag, which suppresses every marketing subscription type on the portal in a single request.

What are the rate limits for the Subscriptions API?

Standard HubSpot API limits — about 100 requests per 10 seconds per OAuth app and daily caps on most paid tiers. Use the batch read and batch write endpoints to stay well below the per-request ceiling.

How do I update a contact's preferences through Jentic?

Search Jentic with `update a HubSpot subscription preference`, load the schema for POST /communication-preferences/v4/statuses/{subscriberIdString}, and execute with the contact email and subscriptionId. Install with `pip install jentic` and authenticate via `JENTIC_AGENT_API_KEY`.

Does this API let me list every subscription type on the portal?

Yes. GET /communication-preferences/v4/definitions returns all subscription type definitions, including IDs and friendly names, so an agent can resolve names to IDs before updating a contact's status.

HubSpot Communication Preferences Subscriptions

Connect the Communication Preferences Subscriptions to your agent

Capabilities

Start building with Communication Preferences Subscriptions API

Use Cases

Key Endpoints

Why Jentic?

Related APIs

FAQs