Communication Preferences Subscriptions

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

✓ Official Vendor SpecMarketingMarketing Automationoauth2, apiKey9 EndpointsREST

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.

Quickstart

Get started with Communication Preferences Subscriptions in minutes using your preferred integration method.

# Add to your MCP client config (Claude Desktop, Cursor, Windsurf)
{
  "jentic": {
    "url": "https://api.jentic.com/mcp",
    "auth": "oauth"
  }
}

# Then ask your agent:
"update a HubSpot subscription preference"

# → Jentic returns the GET /events tool with parameter schema, agent executes.

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

Batch read subscription statuses for many contacts at once

GET STARTED

Start building with Communication Preferences Subscriptions API

Explore with Jentic

View OpenAPI Document

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.

The HubSpot Communication Preferences Subscriptions API exposes a contact's subscription opt-in and opt-out state across HubSpot subscription types. It supports retrieving a contact's preferences, updating individual subscriptions, unsubscribing from all communications, and running batch reads and writes for many contacts at once. Subscription type definitions can also be listed, making this the right surface for compliance with consent-driven marketing such as GDPR and CAN-SPAM.

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

Related APIs

Alternatives and complements available in the Jentic catalogue.

Complementary

HubSpot CRM Contacts

Look up the contact records whose subscription state is being managed.

Use CRM-contacts when the agent needs to find or update the contact record itself before adjusting communication preferences.

Complementary

HubSpot CRM Email Engagements

Log and inspect individual email engagements alongside subscription state.

Pick CRM-emails when the agent needs to associate an unsubscribe with a specific outbound email.

Complementary

HubSpot CRM Lists

Build and inspect lists driven by subscription status.

Use CRM-lists when the agent needs to segment contacts based on opt-in status across one or more subscriptions.

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.