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.

Regional Endpoints

Please use the appropriate API endpoint based on your workspace region:

EU workspaces: https://email.eu-west-1.api.bird.com
US workspaces: https://email.us-west-2.api.bird.com

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 delivery
- delivery: Message was successfully delivered
- delay: Message delivery was delayed
- bounce: Message delivery failed
- spam_complaint: Recipient marked message as spam
- out_of_band: Message bounced after initial acceptance
- policy_rejection: Message was rejected by policy
- generation_failure: Message generation failed
- generation_rejection: Message was rejected during generation
Recipient Engagement Events:
- open: Message was opened
- initial_open: First time message was opened
- click: Link in message was clicked
- initial_click: First time a link was clicked
- amp_click: Link in AMP version was clicked
- amp_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:

campaigns
ip_pools
reasons
recipient_domains
sending_domains
subjects
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.

Search Message Events

get

/workspaces/{workspaceId}/reach/events/message

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.

Authorizations

AuthorizationstringRequired

API key for authentication. Format: AccessKey <token> or Bearer <token>.

Path parameters

workspaceIdstring · uuidRequired

The ID of the workspace

Query parameters

fromstring · date-timeOptional

Start datetime (YYYY-MM-DDTHH:MM:ssZ), inclusive. Value should be in UTC. Default is 24 hours ago.

tostring · date-timeOptional

End datetime (YYYY-MM-DDTHH:MM:ssZ), exclusive. Value should be in UTC. Default is 1 minute ago.

cursorstringOptional

Results cursor for pagination. Used in conjunction with the per_page parameter. See the Pagination section for more information.

Default: initial

per_pageinteger · min: 1 · max: 10000Optional

Results per page

Default: 1000

delimiterstringOptional

Specifies the delimiter for query parameter lists

Default: ,

event_idsstringOptional

Comma delimited list of event IDs to search

eventsstringOptional

Comma delimited list of event types to search

Default: all event types

recipientsstringOptional

Comma delimited list of recipients to search

recipient_domainsstringOptional

Comma delimited list of recipient domains to search. Supports keyword searching by domain segment

from_addressesstringOptional

Comma delimited list of friendly from addresses to search

sending_domainsstringOptional

Comma delimited list of sending domains to search. Supports keyword searching by domain segment

subjectsstringOptional

Comma delimited list of subject lines from the email header to search. Supports keyword searching

bounce_classesstringOptional

Comma delimited list of bounce classification codes to search. See the Bounce Classification Codes documentation for more information.

reasonsstringOptional

Comma delimited list of bounce/failure/rejection reasons to search. Supports keyword searching

campaignsstringOptional

Comma delimited list of campaign IDs to search. Supports keyword searching

sending_ipsstringOptional

Comma delimited list of sending IP addresses to search

ip_poolsstringOptional

Comma delimited list of IP pool IDs to search. Supports keyword searching

subaccountsstringOptional

Comma delimited list of subaccount IDs to search

messagesstringOptional

Comma delimited list of message IDs to search

transmissionsstringOptional

Comma delimited list of transmission IDs to search

mailbox_providersstringOptional

Comma delimited list of mailbox providers to search. Supports keyword searching

mailbox_provider_regionsstringOptional

Comma delimited list of mailbox provider regions to search. Supports keyword searching

Responses

200

Successfully retrieved events

application/json

400

Request validation error

application/json

get

/workspaces/{workspaceId}/reach/events/message

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",
      "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": {}
}

Last updated 3 months ago

Was this helpful?

hashtagRegional Endpoints

hashtagData Retention

hashtagEvent Types

hashtagKeyword Searching

hashtagPagination

hashtagSearch Message Events