There's a new version of the HubSpot API

As of November 30, 2022, HubSpot API keys are no longer a supported authentication method for accessing HubSpot APIs. Instead, you should use a private app access token or OAuth to authenticate API calls. Learn more about this change and how to migrate an API key integration to use a private app instead.

Email Subscriptions API Overview

Subscriptions timeline

The subscriptions timeline endpoint provides a reverse-chronological listing of subscription-related changes affecting your HubSpot account. Changes are grouped into timeline items, which are per-recipient. Further, all changes caused by the same email event will be grouped into the same timeline item.

Use case for this API: The Email Subscriptions API can be used to build integrations with other Business Intelligence (BI) systems for reporting. 

Timeline items have the following properties:

Property name Type Description
timestamp 64-bit integer The timestamp (in milliseconds since epoch) when the changes in this item occurred.
portalId 32-bit integer An ID referencing the HubSpot account associated with the item. This will correspond to your account.
recipient string The email address of the subscriber.
changes JSON An array of JSON objects representing the subscription changes. See below for details on the contents of these objects.
snapshot JSON A JSON object representing the full state of the recipient's subscriptions at the referenced timestamp (with the changes applied). This is equivalent to what this endpoint would have returned at that time.

Subscription changes

Each subscription change object represents a single change in a recipient's overall subscription status. A change object contains the following properties:

Property name Type Description
timestamp 64-bit integer The timestamp (in milliseconds since epoch) when this change occurred. If 'causedByEvent' is present, this will be absent.
causedByEvent EventId The EventId of the email event that caused this change. Refer to the Email Events API Overview for more information on EventIds and how to use them.
source string (enumeration) The source of the subscription change. Refer to the Email Events API Overview for more information on the possible sources of subscription changes.
changeType string (enumeration) The type of change which occurred. See below for the possible values.
change string (enumeration) The change which occurred. This enumeration is specific to the 'changeType'; see below for the possible values.
subscriptionId 64-bit integer An ID referencing the email subscription associated with the change. Additional information on the email subscription can be found via this endpoint.
portalId 32-bit integer An ID referencing the HubSpot account associated with the change. This will correspond to your account.

Change types

There are five change types:

Change type Description
SUBSCRIPTION_STATUS The recipient either SUBSCRIBED to or UNSUBSCRIBED from the email subscription referenced by 'subscriptionId'.
PORTAL_STATUS The recipient either SUBSCRIBED to or UNSUBSCRIBED from all emails sent by the account.
SUBSCRIPTION_SPAM_REPORT The recipient flagged an email for 'subscriptionId' as spam (REPORTED_SPAM), or the spam report was cleared by some means (CLEARED_SPAM_REPORT).
PORTAL_SPAM_REPORT The recipient flagged an email from the account as spam (REPORTED_SPAM), or the spam report was cleared by some means (CLEARED_SPAM_REPORT).
PORTAL_BOUNCE An email to the recipient BOUNCED, or the bounce status was cleared by some means (CLEARED_BOUNCE).

In addition, when submitting a timeline query, the following additional enumeration values may be used:

Change type Description
ANY_STATUS Any type of status change, eg either SUBSCRIPTION_STATUS or PORTAL_STATUS.
ANY_SPAM_REPORT Any type of spam report change, eg either SUBSCRIPTION_SPAM_REPORT or PORTAL_SPAM_REPORT.
ANY_BOUNCE Any type of bounce change, eg PORTAL_BOUNCE.

The Email Events API Overview has additional information about spam reports and bounces.

Docs for this section or API