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_tests
campaigns
ip_pools
reasons
recipient_domains
sending_domains
subjects
templates
mailbox_providers
mailbox_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.
Returns message events matching the filtered search. Data retention: 10 days for events, 6 months for aggregate reporting.
Note: Maximum URI length is 4096 characters.
The ID of the workspace
Start datetime (YYYY-MM-DDTHH:MM:ssZ
), inclusive. Value should be in UTC. Default is 24 hours ago.
End datetime (YYYY-MM-DDTHH:MM:ssZ
), exclusive. Value should be in UTC. Default is 1 minute ago.
Results cursor for pagination. Used in conjunction with the per_page
parameter. See the Pagination section for more information.
initial
Results per page
1000
Specifies the delimiter for query parameter lists
,
Comma delimited list of event IDs to search
Comma delimited list of event types to search
all event types
Comma delimited list of recipients to search
Comma delimited list of recipient domains to search. Supports keyword searching by domain segment
Comma delimited list of friendly from addresses to search
Comma delimited list of sending domains to search. Supports keyword searching by domain segment
Comma delimited list of subject lines from the email header to search. Supports keyword searching
Comma delimited list of bounce classification codes to search. See the Bounce Classification Codes documentation for more information.
Comma delimited list of bounce/failure/rejection reasons to search. Supports keyword searching
Comma delimited list of campaign IDs to search. Supports keyword searching
Comma delimited list of template IDs to search. Supports keyword searching
Comma delimited list of sending IP addresses to search
Comma delimited list of IP pool IDs to search. Supports keyword searching
Comma delimited list of subaccount IDs to search
Comma delimited list of message IDs to search
Comma delimited list of transmission IDs to search
Comma delimited list of mailbox providers to search. Supports keyword searching
Comma delimited list of mailbox provider regions to search. Supports keyword searching
Comma delimited list of A/B test IDs to search. Supports keyword searching
Comma delimited list of version numbers of A/B tests to search. If provided, ab_tests parameter becomes required
GET /api/workspaces/{workspaceId}/reach/events/message HTTP/1.1
Host: email.eu-west-1.api.bird.com
Authorization: YOUR_API_KEY
Accept: */*
{
"results": [
{
"type": "click",
"campaign_id": "Example Campaign Name",
"customer_id": "1",
"delv_method": "esmtp",
"event_id": "92356927693813856",
"friendly_from": "[email protected]",
"geo_ip": {
"country": "US",
"region": "MD",
"city": "Columbia",
"latitude": "39.1749",
"longitude": "-76.8375"
},
"injection_time": "2016-04-18T14:25:07.000+00:00",
"ip_address": "127.0.0.1",
"ip_pool": "Example-Ip-Pool",
"message_id": "000443ee14578172be22",
"msg_from": "[email protected]",
"msg_size": "1337",
"num_retries": "2",
"queue_time": "12",
"rcpt_meta": {
"customKey": "customValue",
"anotherKey": [
"value1",
"value2",
"value3"
]
},
"rcpt_tags": [
"male",
"US"
],
"rcpt_to": "[email protected]",
"raw_rcpt_to": "[email protected]",
"rcpt_type": "cc",
"recipient_domain": "example.com",
"routing_domain": "example.com",
"sending_domain": "example.com",
"sending_ip": "127.0.0.1",
"subaccount_id": "101",
"subject": "Summer deals are here!",
"target_link_name": "Example Link Name",
"target_link_url": "http://example.com",
"template_id": "my-template",
"template_version": "1",
"timestamp": "2016-04-18T14:25:07.000+00:00",
"transmission_id": "65832150921904138",
"user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/41.0.2272.118 Safari/537.36",
"mailbox_provider": "Gmail",
"mailbox_provider_region": "Europe"
}
],
"total_count": 1,
"links": {}
}
Was this helpful?