Events
The Events API allows searching for recent events, and supports various types of result filtering. Available events include message status (injection, delivery, bounce) as well as recipient engagement (clicks and opens). You can fetch all event types or only specific ones, such as bounces, deliveries, or clicks. You can also filter by date range, campaign, or just about any other field.
Note: The maximum URI length is 4096 characters, so please keep your queries below that size when adding filters.
Data Retention
Events data is retained for 10 days
Aggregate reporting data is available through metrics or the app for up to 6 months
Event Types
The following types of events can be queried from the Events API:
Message Status Events:
injection: Message was accepted for deliverydelivery: Message was successfully delivereddelay: Message delivery was delayedbounce: Message delivery failedspam_complaint: Recipient marked message as spamout_of_band: Message bounced after initial acceptancepolicy_rejection: Message was rejected by policygeneration_failure: Message generation failedgeneration_rejection: Message was rejected during generation
Recipient Engagement Events:
open: Message was openedinitial_open: First time message was openedclick: Link in message was clickedinitial_click: First time a link was clickedamp_click: Link in AMP version was clickedamp_open: AMP version was opened
Keyword Searching
Some filter parameters support keyword searching, allowing filtering without precise values and multiple values without listing each one. Keywords are determined by natural breaks in phrases by spaces, dashes, underscores, and in special cases periods. The following filters support keyword searching:
ab_testscampaignsip_poolsreasonsrecipient_domainssending_domainssubjectstemplatesmailbox_providersmailbox_provider_regions
Pagination
The Events API supports pagination for queries with larger result sets. Pagination is done through the use of the cursor and per_page query parameters.
The per_page query parameter tells the Events API the number of events to return in a single request, and supports a maximum value of 10,000.
To start a paging request, add the query parameter ?cursor=initial to your Events API request. This will fetch the first page of results. If cursor is not provided, then the default value of initial is applied.
In the response body, there are three main keys: results, total_count and links. results is an array which contains the page of JSON events that matched the request,total_count is an integer that describes the total number of JSON events that matched your request, and links is an object which provides a way to request the next page of events, if there is more than one page.
Once you have the response, you then can use links to retrieve the URL for your next page, which will be prefilled with the appropriate value for the cursor query parameter,
as well as any other filters you supplied with the original request.
In the following examples, to retrieve the first page, we use the initial value for the cursor query parameter. Then use the cursor value from
the next key in the links object to make the request for the second page. This process would then be repeated until all results have been paged through,
at which point the links object will not have a next key, and no further additional requests are necessary.
If your result set is less than one page of data, then the links object will not have a next key.
Note: Pagination requests count towards the number of requests allowed by rate limiting, the same as non-paginated requests.
Was this helpful?