Email Subscriptions Overview

Subscriptions Timeline

The subscriptions timeline endpoint provides a reverse-chronological listing of subscription-related changes which affect your HubSpot Portal. 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.

Timeline items have the following properties:

Property NameTypeDescription
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 Portal which is associated with the item. This will correspond to your portal.
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 NameTypeDescription
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 which caused this change. Refer to the Email Events Bible for more information on EventIds and how to use them.
source string (enumeration) The source of the subscription change. Refer to the Email Events Bible 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 which is 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 Portal which is associated with the change. This will correspond to your portal.

Change Types

There are 5 different change types:

Change TypeDescription
SUBSCRIPTION_STATUS The recipient either SUBSCRIBED to or UNSUBSCRIBED from to the email subscription referenced by 'subscriptionId'.
PORTAL_STATUS The recipient either SUBSCRIBED to or UNSUBSCRIBED from all emails sent by the portal.
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 portal 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 TypeDescription
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 Bible has additional information about spam reports and bounces.

Docs for this section or API