Actions

The ballerinax/hubspot.marketing.subscriptions package exposes the following clients:

Client	Purpose
`Client`	Manages contact subscription statuses, opt-outs, and subscription definitions via the HubSpot Communication Preferences API v4.

Client

Manages contact subscription statuses, opt-outs, and subscription definitions via the HubSpot Communication Preferences API v4.

Configuration

Field	Type	Default	Description
`auth`	`http:BearerTokenConfig\|OAuth2RefreshTokenGrantConfig\|ApiKeysConfig`	Required	OAuth 2.0 refresh token config, bearer token, or API key credentials.
`httpVersion`	`http:HttpVersion`	`HTTP_2_0`	HTTP protocol version.
`timeout`	`decimal`	`30`	Request timeout in seconds.
`retryConfig`	`http:RetryConfig`	`()`	Retry configuration for failed requests.
`secureSocket`	`http:ClientSecureSocket`	`()`	SSL/TLS configuration.
`proxy`	`http:ProxyConfig`	`()`	Proxy server configuration.
`compression`	`http:Compression`	`COMPRESSION_AUTO`	HTTP compression setting.
`circuitBreaker`	`http:CircuitBreakerConfig`	`()`	Circuit breaker configuration.
`cache`	`http:CacheConfig`	`{}`	HTTP response cache configuration.
`validation`	`boolean`	`true`	Enable/disable constraint validation.
`laxDataBinding`	`boolean`	`true`	Enable/disable lax data binding.

Initializing the client

import ballerinax/hubspot.marketing.subscriptions as hsmsubscriptions;

configurable string clientId = ?;
configurable string clientSecret = ?;
configurable string refreshToken = ?;

hsmsubscriptions:Client subscriptionsClient = check new ({
    auth: {
        clientId: clientId,
        clientSecret: clientSecret,
        refreshToken: refreshToken,
        credentialBearer: oauth2:POST_BODY_BEARER
    }
});

Operations

Subscription status: single contact

getCommunicationPreferencesV4StatusesSubscriberIdString

Retrieves the subscription statuses for a specific contact on a given channel.

Parameters:

Name	Type	Required	Description
`subscriberIdString`	`string`	Yes	The contact's subscriber ID (e.g., email address).
`headers`	`map<string\|string[]>`	No	Optional HTTP headers.
`queries`	`GetCommunicationPreferencesV4StatusesSubscriberIdStringQueries`	Yes	Query parameters including `channel` (required) and optional `businessUnitId`.

Returns: ActionResponseWithResultsPublicStatus|error

Sample code:

hsmsubscriptions:ActionResponseWithResultsPublicStatus response =
    check subscriptionsClient->getCommunicationPreferencesV4StatusesSubscriberIdString(
        "[email protected]",
        queries = {channel: "EMAIL"}
    );

Sample response:

{
  "status": "COMPLETE",
  "results": [
    {
      "subscriberIdString": "[email protected]",
      "subscriptionId": 12345,
      "subscriptionName": "Marketing Newsletter",
      "channel": "EMAIL",
      "status": "SUBSCRIBED",
      "source": "SUBSCRIPTION_STATUS",
      "legalBasis": "CONSENT_WITH_NOTICE",
      "legalBasisExplanation": "User opted in via website form",
      "timestamp": "2025-06-15T10:30:00Z"
    }
  ],
  "startedAt": "2025-06-15T10:30:00.123Z",
  "completedAt": "2025-06-15T10:30:00.456Z"
}

postCommunicationPreferencesV4StatusesSubscriberIdString

Updates the subscription status for a specific contact.

Parameters:

Name	Type	Required	Description
`subscriberIdString`	`string`	Yes	The contact's subscriber ID (e.g., email address).
`payload`	`PartialPublicStatusRequest`	Yes	The subscription status update payload including `statusState`, `channel`, and `subscriptionId`.
`headers`	`map<string\|string[]>`	No	Optional HTTP headers.

Returns: ActionResponseWithResultsPublicStatus|error

Sample code:

hsmsubscriptions:ActionResponseWithResultsPublicStatus response =
    check subscriptionsClient->postCommunicationPreferencesV4StatusesSubscriberIdString(
        "[email protected]",
        {
            statusState: "SUBSCRIBED",
            channel: "EMAIL",
            subscriptionId: 12345,
            legalBasis: "CONSENT_WITH_NOTICE",
            legalBasisExplanation: "User opted in via website form"
        }
    );

Sample response:

{
  "status": "COMPLETE",
  "results": [
    {
      "subscriberIdString": "[email protected]",
      "subscriptionId": 12345,
      "subscriptionName": "Marketing Newsletter",
      "channel": "EMAIL",
      "status": "SUBSCRIBED",
      "source": "SUBSCRIPTION_STATUS",
      "legalBasis": "CONSENT_WITH_NOTICE",
      "legalBasisExplanation": "User opted in via website form",
      "setStatusSuccessReason": "REQUESTED_CHANGE_OCCURRED",
      "timestamp": "2025-06-15T11:00:00Z"
    }
  ],
  "startedAt": "2025-06-15T11:00:00.123Z",
  "completedAt": "2025-06-15T11:00:00.456Z"
}

Unsubscribe all: single contact

getCommunicationPreferencesV4StatusesSubscriberIdStringUnsubscribeAll

Retrieves the opt-out-of-all (wide) status for a specific contact on a given channel.

Parameters:

Name	Type	Required	Description
`subscriberIdString`	`string`	Yes	The contact's subscriber ID (e.g., email address).
`headers`	`map<string\|string[]>`	No	Optional HTTP headers.
`queries`	`GetCommunicationPreferencesV4StatusesSubscriberIdStringUnsubscribeAllQueries`	Yes	Query parameters including `channel` (required), optional `businessUnitId` and `verbose`.

Returns: ActionResponseWithResultsPublicWideStatus|error

Sample code:

hsmsubscriptions:ActionResponseWithResultsPublicWideStatus response =
    check subscriptionsClient->getCommunicationPreferencesV4StatusesSubscriberIdStringUnsubscribeAll(
        "[email protected]",
        queries = {channel: "EMAIL"}
    );

Sample response:

{
  "status": "COMPLETE",
  "results": [
    {
      "subscriberIdString": "[email protected]",
      "channel": "EMAIL",
      "wideStatusType": "PORTAL_WIDE",
      "status": "SUBSCRIBED",
      "timestamp": "2025-06-15T10:30:00Z"
    }
  ],
  "startedAt": "2025-06-15T10:30:00.123Z",
  "completedAt": "2025-06-15T10:30:00.456Z"
}

postCommunicationPreferencesV4StatusesSubscriberIdStringUnsubscribeAll

Unsubscribes a contact from all communication subscriptions on a given channel.

Parameters:

Name	Type	Required	Description
`subscriberIdString`	`string`	Yes	The contact's subscriber ID (e.g., email address).
`headers`	`map<string\|string[]>`	No	Optional HTTP headers.
`queries`	`PostCommunicationPreferencesV4StatusesSubscriberIdStringUnsubscribeAllQueries`	Yes	Query parameters including `channel` (required), optional `businessUnitId` and `verbose`.

Returns: ActionResponseWithResultsPublicStatus|error

Sample code:

hsmsubscriptions:ActionResponseWithResultsPublicStatus response =
    check subscriptionsClient->postCommunicationPreferencesV4StatusesSubscriberIdStringUnsubscribeAll(
        "[email protected]",
        queries = {channel: "EMAIL"}
    );

Sample response:

{
  "status": "COMPLETE",
  "results": [
    {
      "subscriberIdString": "[email protected]",
      "subscriptionId": 12345,
      "subscriptionName": "Marketing Newsletter",
      "channel": "EMAIL",
      "status": "UNSUBSCRIBED",
      "source": "SUBSCRIPTION_STATUS",
      "setStatusSuccessReason": "UNSUBSCRIBE_FROM_ALL_OCCURRED",
      "timestamp": "2025-06-15T11:00:00Z"
    }
  ],
  "startedAt": "2025-06-15T11:00:00.123Z",
  "completedAt": "2025-06-15T11:00:00.456Z"
}

Batch subscription operations

postCommunicationPreferencesV4StatusesBatchRead

Batch retrieves subscription statuses for multiple contacts on a given channel.

Parameters:

Name	Type	Required	Description
`payload`	`BatchInputString`	Yes	A batch input containing an array of subscriber ID strings.
`headers`	`map<string\|string[]>`	No	Optional HTTP headers.
`queries`	`PostCommunicationPreferencesV4StatusesBatchReadQueries`	Yes	Query parameters including `channel` (required) and optional `businessUnitId`.

Returns: BatchResponsePublicStatusBulkResponse|BatchResponsePublicStatusBulkResponseWithErrors|error

Sample code:

hsmsubscriptions:BatchResponsePublicStatusBulkResponse|hsmsubscriptions:BatchResponsePublicStatusBulkResponseWithErrors response =
    check subscriptionsClient->postCommunicationPreferencesV4StatusesBatchRead(
        {inputs: ["[email protected]", "[email protected]"]},
        queries = {channel: "EMAIL"}
    );

Sample response:

{
  "status": "COMPLETE",
  "results": [
    {
      "subscriberIdString": "[email protected]",
      "statuses": [
        {
          "subscriberIdString": "[email protected]",
          "subscriptionId": 12345,
          "subscriptionName": "Marketing Newsletter",
          "channel": "EMAIL",
          "status": "SUBSCRIBED",
          "source": "SUBSCRIPTION_STATUS",
          "timestamp": "2025-06-15T10:30:00Z"
        }
      ]
    },
    {
      "subscriberIdString": "[email protected]",
      "statuses": [
        {
          "subscriberIdString": "[email protected]",
          "subscriptionId": 12345,
          "subscriptionName": "Marketing Newsletter",
          "channel": "EMAIL",
          "status": "UNSUBSCRIBED",
          "source": "SUBSCRIPTION_STATUS",
          "timestamp": "2025-06-15T09:00:00Z"
        }
      ]
    }
  ],
  "startedAt": "2025-06-15T10:30:00.123Z",
  "completedAt": "2025-06-15T10:30:00.789Z"
}

postCommunicationPreferencesV4StatusesBatchWrite

Batch updates subscription statuses for multiple contacts.

Parameters:

Name	Type	Required	Description
`payload`	`BatchInputPublicStatusRequest`	Yes	A batch input containing an array of `PublicStatusRequest` records.
`headers`	`map<string\|string[]>`	No	Optional HTTP headers.

Returns: BatchResponsePublicStatus|error

Sample code:

hsmsubscriptions:BatchResponsePublicStatus response =
    check subscriptionsClient->postCommunicationPreferencesV4StatusesBatchWrite({
        inputs: [
            {
                subscriberIdString: "[email protected]",
                statusState: "SUBSCRIBED",
                channel: "EMAIL",
                subscriptionId: 12345,
                legalBasis: "CONSENT_WITH_NOTICE",
                legalBasisExplanation: "Re-subscribed via preference center"
            },
            {
                subscriberIdString: "[email protected]",
                statusState: "SUBSCRIBED",
                channel: "EMAIL",
                subscriptionId: 12345,
                legalBasis: "CONSENT_WITH_NOTICE",
                legalBasisExplanation: "Re-subscribed via preference center"
            }
        ]
    });

Sample response:

{
  "status": "COMPLETE",
  "results": [
    {
      "subscriberIdString": "[email protected]",
      "subscriptionId": 12345,
      "subscriptionName": "Marketing Newsletter",
      "channel": "EMAIL",
      "status": "SUBSCRIBED",
      "source": "SUBSCRIPTION_STATUS",
      "legalBasis": "CONSENT_WITH_NOTICE",
      "legalBasisExplanation": "Re-subscribed via preference center",
      "setStatusSuccessReason": "REQUESTED_CHANGE_OCCURRED",
      "timestamp": "2025-06-15T11:00:00Z"
    },
    {
      "subscriberIdString": "[email protected]",
      "subscriptionId": 12345,
      "subscriptionName": "Marketing Newsletter",
      "channel": "EMAIL",
      "status": "SUBSCRIBED",
      "source": "SUBSCRIPTION_STATUS",
      "legalBasis": "CONSENT_WITH_NOTICE",
      "legalBasisExplanation": "Re-subscribed via preference center",
      "setStatusSuccessReason": "REQUESTED_CHANGE_OCCURRED",
      "timestamp": "2025-06-15T11:00:00Z"
    }
  ],
  "startedAt": "2025-06-15T11:00:00.123Z",
  "completedAt": "2025-06-15T11:00:00.789Z"
}

postCommunicationPreferencesV4StatusesBatchUnsubscribeAll

Batch unsubscribes multiple contacts from all communication subscriptions on a given channel.

Parameters:

Name	Type	Required	Description
`payload`	`BatchInputString`	Yes	A batch input containing an array of subscriber ID strings.
`headers`	`map<string\|string[]>`	No	Optional HTTP headers.
`queries`	`PostCommunicationPreferencesV4StatusesBatchUnsubscribeAllQueries`	Yes	Query parameters including `channel` (required), optional `businessUnitId` and `verbose`.

Returns: BatchResponsePublicBulkOptOutFromAllResponse|error

Sample code:

hsmsubscriptions:BatchResponsePublicBulkOptOutFromAllResponse response =
    check subscriptionsClient->postCommunicationPreferencesV4StatusesBatchUnsubscribeAll(
        {inputs: ["[email protected]", "[email protected]"]},
        queries = {channel: "EMAIL"}
    );

Sample response:

{
  "status": "COMPLETE",
  "results": [
    {
      "subscriberIdString": "[email protected]",
      "statuses": [
        {
          "subscriberIdString": "[email protected]",
          "subscriptionId": 12345,
          "channel": "EMAIL",
          "status": "UNSUBSCRIBED",
          "source": "SUBSCRIPTION_STATUS",
          "timestamp": "2025-06-15T11:00:00Z"
        }
      ]
    },
    {
      "subscriberIdString": "[email protected]",
      "statuses": [
        {
          "subscriberIdString": "[email protected]",
          "subscriptionId": 12345,
          "channel": "EMAIL",
          "status": "UNSUBSCRIBED",
          "source": "SUBSCRIPTION_STATUS",
          "timestamp": "2025-06-15T11:00:00Z"
        }
      ]
    }
  ],
  "startedAt": "2025-06-15T11:00:00.123Z",
  "completedAt": "2025-06-15T11:00:00.789Z"
}

postCommunicationPreferencesV4StatusesBatchUnsubscribeAllRead

Batch retrieves the opt-out-of-all (wide) statuses for multiple contacts on a given channel.

Parameters:

Name	Type	Required	Description
`payload`	`BatchInputString`	Yes	A batch input containing an array of subscriber ID strings.
`headers`	`map<string\|string[]>`	No	Optional HTTP headers.
`queries`	`PostCommunicationPreferencesV4StatusesBatchUnsubscribeAllReadQueries`	Yes	Query parameters including `channel` (required) and optional `businessUnitId`.

Returns: BatchResponsePublicWideStatusBulkResponse|BatchResponsePublicWideStatusBulkResponseWithErrors|error

Sample code:

hsmsubscriptions:BatchResponsePublicWideStatusBulkResponse|hsmsubscriptions:BatchResponsePublicWideStatusBulkResponseWithErrors response =
    check subscriptionsClient->postCommunicationPreferencesV4StatusesBatchUnsubscribeAllRead(
        {inputs: ["[email protected]", "[email protected]"]},
        queries = {channel: "EMAIL"}
    );

Sample response:

{
  "status": "COMPLETE",
  "results": [
    {
      "subscriberIdString": "[email protected]",
      "wideStatuses": [
        {
          "subscriberIdString": "[email protected]",
          "channel": "EMAIL",
          "wideStatusType": "PORTAL_WIDE",
          "status": "SUBSCRIBED",
          "timestamp": "2025-06-15T10:30:00Z"
        }
      ]
    },
    {
      "subscriberIdString": "[email protected]",
      "wideStatuses": [
        {
          "subscriberIdString": "[email protected]",
          "channel": "EMAIL",
          "wideStatusType": "PORTAL_WIDE",
          "status": "UNSUBSCRIBED",
          "timestamp": "2025-06-15T09:00:00Z"
        }
      ]
    }
  ],
  "startedAt": "2025-06-15T10:30:00.123Z",
  "completedAt": "2025-06-15T10:30:00.789Z"
}

Subscription definitions

getCommunicationPreferencesV4Definitions

Retrieves all subscription definitions configured in the HubSpot portal.

Parameters:

Name	Type	Required	Description
`headers`	`map<string\|string[]>`	No	Optional HTTP headers.
`queries`	`GetCommunicationPreferencesV4DefinitionsQueries`	No	Query parameters including optional `includeTranslations` and `businessUnitId`.

Returns: ActionResponseWithResultsSubscriptionDefinition|error

Sample code:

hsmsubscriptions:ActionResponseWithResultsSubscriptionDefinition response =
    check subscriptionsClient->getCommunicationPreferencesV4Definitions();

Sample response:

{
  "status": "COMPLETE",
  "results": [
    {
      "id": "12345",
      "name": "Marketing Newsletter",
      "description": "Monthly marketing updates and product news",
      "purpose": "Marketing",
      "communicationMethod": "Email",
      "isActive": true,
      "isDefault": false,
      "isInternal": false,
      "createdAt": "2024-01-15T08:00:00Z",
      "updatedAt": "2025-03-10T14:30:00Z"
    },
    {
      "id": "12346",
      "name": "Product Updates",
      "description": "Notifications about new features and releases",
      "purpose": "Marketing",
      "communicationMethod": "Email",
      "isActive": true,
      "isDefault": false,
      "isInternal": false,
      "createdAt": "2024-02-20T10:00:00Z",
      "updatedAt": "2025-03-10T14:30:00Z"
    }
  ],
  "startedAt": "2025-06-15T10:30:00.123Z",
  "completedAt": "2025-06-15T10:30:00.456Z"
}

Client​

Configuration​

Initializing the client​

Operations​

Subscription status: single contact​

Unsubscribe all: single contact​

Batch subscription operations​

Subscription definitions​

Client

Configuration

Initializing the client

Operations

Subscription status: single contact

Unsubscribe all: single contact

Batch subscription operations

Subscription definitions