Skip to main content

Use the email analytics API to fetch events generated by marketing emails, such as sends, bounces, and clicks.

To optimize email campaigns, you want to gather data to power a machine learning model that determines the best time to send emails to different contact segments.

GET

/email/public/v1/campaigns/by-id

For a given portal, return all email campaign IDs associated with the portal. The email campaign IDs are returned in no particular order. You can then use the IDs to look up data on the performance of each marketing email campaign.

Note that you can get campaign IDs with recent activity via this endpoint instead.

Requirements
Scopes
  1. content
Auth Methods

Private apps

OAuth

Parameters
offset

Query param

A key representing which page of results you would like

limit

Query param

Limit the maximum number of results you would like returned.

Response

Show more

Get campaign IDs with recent activity for a portal

GET

/email/public/v1/campaigns

For a given portal, return all campaign IDs sorted by recent activity associated with the portal. The campaign IDs are returned in descending order of most-recent activity. You can then use the IDs to look up data on the perfomance of each campaign.

Requirements
Auth Methods

Private apps

OAuth

Parameters
offset

Query param

A key representing which page of results you would like

limit

Query param

Limit the maximum number of results you would like returned.

Response

Show more

GET

/email/public/v1/campaigns/:campaign_id

This endpoint provides a way to query data associated with a given email campaign.

To find the campaign_id that corresponds to a specific email:

  • In your HubSpot account, navigate to Marketing > Email.
  • Locate the sent email you want to retrieve campaign data for, then click the email name.
  • Under the Sent date, click See details.
  • In the right panel, the campaign_id will be listed under Internal HubSpot ID.

legacy-marketing-email-api-find-campaign-id

The campaign_id will also be provided within the allEmailCampaignIds field in the response of the Marketing Email Statistics API.

Requirements
Scopes
  1. content
Auth Methods

Private apps

OAuth

Parameters
campaign_id*

Path param

The Internal HubSpot ID of the email that you want to get the details for. Consult the section above this table to learn how to locate this ID.

Response

Show more

GET

/email/public/v1/events

This endpoint is used to query the event log for events matching specified parameters.

The parameters offset and limit are used to paginate results.

The returned offset is an opaque token used internally to keep track of the position in the result set. It's not meant to be used for anything other than subsequent requests on this endpoint with the same query parameters (excluding offset itself and limit). Further, it's meant to be short-lived.

Requirements
Scopes
  1. content
Auth Methods

Private apps

OAuth

Parameters
appId

Query param

Only return events which correspond to the given HubSpot Application ID.

campaignId

Query param

Only return events from the given HubSpot Campaign ID.

recipient

Query param

Only return events related to the given recipient.

eventType

Query param

Only return events of the specified type (case-sensitive). The possible types are described in the Email Events Overview.

startTimestamp

Query param

Only return events which occurred at or after the given timestamp (in milliseconds since epoch).

endTimestamp

Query param

Only return events which occurred at or before the given timestamp (in milliseconds since epoch).

offset

Query param

An offset token returned by a previous call to this endpoint.

limit

Query param

The maximum number of events to return. If omitted, the default value of 10 is used. The maximum allowed value is 1000.

excludeFilteredEvents

Query param

Only return events that have not been filtered out due to customer filtering settings. The default value is false.

Response

Show more

Events will be returned in reverse-chronological order.

Refer to the Email Events Overview for a full description of events, including the different event types, what they represent, how they're related, and their properties.

GET

/email/public/v1/events/:created/:id

Query the event log for a specific event and get results for that email event.

Refer to the Email Events Overview for a full description of events, including the different event types, what they represent, how they're related, and their properties.

Requirements
Scopes
  1. content
Auth Methods

Private apps

OAuth

Parameters
created*

Path param

The creation timestamp (in milliseconds since epoch) of the event to return.

id*

Path param

The unique ID of the event to return.

Response

Show more