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.

Get the statistics of all marketing emails

Last updated May 15, 2023

GET /marketing-emails/v1/emails/with-statistics

Method Details

HTTP Methods:

GET

Response Format:

json

Requires Authentication?

Yes

Rate Limited?

Yes

Headers

User-Agent

Products:

Marketing

Required Scope:

content

Get the statistics for all marketing emails. These include the same parameters returned from the 'get all marketing emails' and 'get a marketing email' endpoints, in addition to the performance related metrics described in the table below.

 

 

Note: To fetch stats from a campaignid, please refer to the Email Events API.
Required Parameters How to use Description
OAuth access token or private app access token Authorization: Bearer {token} header Used to authenticate the request. Please see this page for more details about authentication.

Optional Parameters How to use Description
Limit &limit=
Used in the request URL
The number of records to return in the response. Defaults to 10
Offset &offset=
Used in the request URL
Used to get the next page of results. Use the limit of the previous request as the offset to get the next set of results.
Order by &orderBy=
Used in the request URL
Return the emails ordered by a particular field value. Use a negative value to sort in descending order (e.g. orderBy=-created).

JSON Fields returned in the 'stats' field

Parameter name Type Description
sent Integer the total number of sent emails
open Integer The total number of unique opens
delivered Integer The number of emails succesfully delivered to an inbox
bounce Integer The number of times contacts were sent your email, but they didn’t receive it because either their address is invalid, your email hit their spam filter, or your email was marked as spam by other people.
unsubscribed Integer The number of contacts who received your email and unsubscribed. They won’t be sent to in the future.
click Integer The number of unique recipients who clicked on any link in your email, excluding the Unsubscribe and Subscription Preferences links.
dropped Integer The number of contacts that were not sent your email. This may be because they previously hard bounced, unsubscribed, marked you as spam, or because they have not engaged with any of your recent emails.
selected Integer  The number of contacts selected to receive this email.
spamreport Integer The number of contacts received your email and marked it as spam. They won’t be sent to in the future.
suppressed Integer The number of contacts that did not receive your email due to graymail suppression.
hardbounced Integer These contacts were sent your email, but they didn’t receive it because either their address is invalid, your email hit their spam filter, or your email was marked as spam by other people.
softbounced Integer Soft bounces occur when a contact’s inbox has a temporary problem. You can still send to these people in the future. Contacts who hard bounce will be ineligible for later sends.
pending Integer The number of emails still trying to reach a contact's inbox.
contactslost Integer The sum of contacts that have unsubscribed, marked the email as spam, or have hardbounced.
notsent Integer These contacts were not sent your email. This may be because they previously hard bounced, unsubscribed, marked you as spam, or because they have not engaged with any of your recent emails.
clickratio Integer Click rate is the percentage of people who clicked a link in your email out of the people who were delivered your email.
clickthroughratio Integer This is the percentage of people who clicked a link in your email out of the people who opened your email.
deliveredratio Integer the number of succesfull deliveries over the number of selected contacts.
openratio Integer Open rate is the percentage of people who opened your email out of the people who were delivered your email.
unsubscribedratio Integer the number of contacts that have unsubscribed over the total number of selected contacts
spamreportratio Integer The number of contacts that mark the email as spam over the total number of selected contacts.
hardbounceratio Integer The number of contacts that hard bounced from the email over the total number of selected contacts.
bounceratio Integer The number of contacts that bounced from the email over the total number of selected contacts.
softbounceratio Integer The number of contacts that soft bounced from the email over the total number of selected contacts.
contactslostratio Integer The number of contacts that can no longer recive emails from the portal over the total number of selected contacts.
pendingratio Integer The number of contacts that soft bounced from the email over the total number of selected contacts.
contactslostratio Integer The number of contacts that were selected but not sent to over the total number of selected contacts.

In addition to filtering for an exact match, some fields support other filter types, designated by including two underscores between the field name and the type. For example, you can filter for emails created after December 31, 2018, by including &created__gt=1546318800000 in the request URL.

The list of fields that support filtering, and the supported filter types for those fields are listed below.

Filtering

Results can be filtered based on specific fields. You can filter for a field by including it as a query parameter. For example, you can filter by campaign by including &campaign=:campaign_id in the request URL.

Field name Supported filter types
ab_status eq, exact, in, is, ne, neq, nin, not
ab_test_id eq, exact, is
analytics_page_id eq, exact, is
archived eq, exact, is
campaign eq, exact, is
content_group_id eq, exact, is, in
content_type_id eq, exact, is
created eq, exact, gt, gte, is, lt, lte, range
created_by_id eq, exact, is
domain contains, eq, exact, is, like, nlike, not_like
folder_id eq, exact, in, is, is_null, not_null
name eq, exact, is, in, ilike, icontains
publish_date eq, exact, gt, gte, is, lt, lte, range
subcategory eq, exact, in, is, ne, neq, nin, not
template_path contains, eq, exact, is, like
updated eq, exact, gt, gte, is, lt, lte, range
updated_by_id eq, exact, is