HubSpot Subscription Preferences v4 - API Guide

Introduction

• Subscription types represent lawful communication with contacts via email.
• Contacts can manage email preferences to subscribe only to desired emails.
• v4 subscriptions APIs:
  • Subscribe or unsubscribe contacts programmatically.
  • Unsubscribe a contact from all email communications.
  • Support for Brands add-on.

Required Scopes for v4 Subscription API

General Endpoints

• communication_preferences.read
  • Fetch subscription type definitions and preferences.
• communication_preferences.write
  • Update subscription preferences.
• communication_preferences.read_write
  • Fetch and update preferences, fetch all definitions.

Batch Subscription Endpoints

• Requires Marketing Hub Enterprise subscription.
• communication_preferences.statuses.batch.read
  • Fetch subscription statuses in bulk.
• communication_preferences.statuses.batch.write
  • Manage and update statuses in bulk.

Endpoints and Requests

• Get Subscription Types: GET /communication-preferences/v4/definitions

  • Includes businessUnitId for filtering by brand.
  • Optionally use includeTranslations=true for translations.

• Get Subscription Preferences for Contact

  • Request: GET /communication-preferences/v4/statuses/{subscriberIdString}?channel=EMAIL
  • Subscription status values:
    • SUBSCRIBED
    • UNSUBSCRIBED
    • NOT_SPECIFIED

• Unsubscribe All

  • Request: POST /communication-preferences/v4/statuses/batch/unsubscribe-all/read
  • Check if unsubscribed from all: GET /communication-preferences/v4/statuses/{subscriberIdString}/unsubscribe-all

• Update Subscription Preferences for Contact

  • Request: POST /communication-preferences/v4/statuses/{subscriberIdString}
  • Parameters in request body:
    • subscriptionId
    • statusState (SUBSCRIBED, UNSUBSCRIBED, NOT_SPECIFIED)
    • legalBasis and legalBasisExplanation (if required)
    • channel (currently only EMAIL supported)

Bulk Operations

• Bulk Unsubscribe

  • POST /communication-preferences/v4/statuses/batch/unsubscribe-all
  • Parameters: businessUnitId, channel, verbose

• Update Subscription Types for Multiple Contacts

  • POST /communication-preferences/v4/statuses/batch/write
  • Details of subscription updates provided in inputs field.

Brands Add-on Support

• Provides additional filtering and response fields related to business units.
• Default Account brand uses "businessUnitId": 0.
• Example operations can include businessUnitId to specify brand operations.