There's a new version of the HubSpot API
We're also working on a new documentation website, you're invited to check it out and give us your feedback.
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. |
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. |
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.
