Email analytics
This is a stable API but uses an older format. This means some functionality may not be available (for example test calls and Postman integration).
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
Parameters
A key representing which page of results you would like
Limit the maximum number of results you would like returned.
Response
{
"hasMore": true,
"offset": "MTYxOTkyMDA=",
"campaigns": [
{
"id": 16275278,
"appId": 113,
"appName": "Batch"
},
{
"id": 16273490,
"appId": 113,
"appName": "Batch"
},
{
"id": 16199200,
"appId": 113,
"appName": "Batch"
}
]
}
Get campaign IDs with recent activity for a portal
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
Parameters
A key representing which page of results you would like
Limit the maximum number of results you would like returned.
Response
xxxxxxxxxx
{
"hasMore": true,
"offset": "MTMwNTQ3MjM=",
"campaigns": [
{
"appId": 20185,
"appName": "AbBatch",
"id": 13054799,
"lastUpdatedTime": 1401715797000
},
{
"appId": 20185,
"appName": "AbBatch",
"id": 13054798,
"lastUpdatedTime": 1401715742000
},
{
"appId": 113,
"appName": "Batch",
"id": 13054723,
"lastUpdatedTime": 1401715620076
}
]
}
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.
The campaign_id
will also be provided within the allEmailCampaignIds
field in the response of the Marketing Email Statistics API.
Requirements
Parameters
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
xxxxxxxxxx
Example GET URL:
https://api.hubapi.com/email/public/v1/campaigns/13054799
Example response:
{
"appId": 20185,
"appName": "AbBatch",
"contentId": 933742756,
"counters": {
"delivered": 1,
"open": 1,
"processed": 1,
"sent": 1
},
"id": 13054799,
"name": "Test AB (Variation) ",
"numIncluded": 1,
"numQueued": 1,
"subType": "VariantB",
"subject": "test",
"type": "AB"
}
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
Parameters
Only return events which correspond to the given HubSpot Application ID.
Only return events from the given HubSpot Campaign ID.
Only return events related to the given recipient.
Only return events of the specified type (case-sensitive). The possible types are described in the Email Events Overview.
Only return events which occurred at or after the given timestamp (in milliseconds since epoch).
Only return events which occurred at or before the given timestamp (in milliseconds since epoch).
An offset token returned by a previous call to this endpoint.
The maximum number of events to return. If omitted, the default value of 10 is used. The maximum allowed value is 1000.
Only return events that have not been filtered out due to customer filtering settings. The default value is false.
Response
xxxxxxxxxx
For example, the following sequence of requests steps
through matching events one at a time:
Request:
https://api.hubapi.com/email/public/v1/events?campaignId=13054799&limit=1
Response:
{
"hasMore": true,
"offset": "Ch8KFgjm2seDq_e_-pIBELz25N-QitCv-wEY4tyW5uUo",
"events": [
{ }
]
}
Request:
https://api.hubapi.com/email/public/v1/events?campaignId=13054799&limit=1&offset=Ch8KFgjm2seDq_e_-pIBELz25N-QitCv-wEY4tyW5uUo
Response:
{
"hasMore": true,
"offset": "Ch8KFgjC0cOq15yCtakBEOXx7NT479WQkgEYiNiW5uUo",
"events": [
{ }
]
}
Request:
https://api.hubapi.com/email/public/v1/events?campaignId=13054799&limit=1&offset=Ch8KFgjC0cOq15yCtakBEOXx7NT479WQkgEYiNiW5uUo
Response:
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
Parameters
The creation timestamp (in milliseconds since epoch) of the event to return.
The unique ID of the event to return.
Response
xxxxxxxxxx
Example JSON Output:
{
"appId": 20185,
"appName": "AbBatch",
"browser": {
"family": "Google Image Cache",
"name": "Google Image Cache",
"producer": "",
"producerUrl": "",
"type": "Proxy",
"url": "",
"version": []
},
"created": 1401715797602,
"emailCampaignId": 13054799,
"id": "fb5f4051-0bf9-3b3c-92f4-ffbab071ed66",
"location": {
"city": "Unknown",
"country": "Unknown",
"state": "Unknown"
},
"portalId": 62515,
"recipient": "maxiak@hubspot.com",
"type": "OPEN",
"userAgent": "Mozilla/5.0 (Windows; U; Windows NT 5.1; de; rv:1.9.0.7) Gecko/2009021910 Firefox/3.0.7 (via ggpht.com GoogleImageProxy)"
}