# 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: * US workspaces: ### 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 > 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.
```json {"openapi":"3.0.4","info":{"title":"Reach Email API","version":"1.0"},"tags":[{"name":"Events","description":"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.\n**Note:** The maximum URI length is 4096 characters, so please keep your queries below that size when adding filters.\n\n---\n\n## Regional Endpoints\n\nPlease use the appropriate API endpoint based on your workspace region:\n\n- EU workspaces: https://email.eu-west-1.api.bird.com\n\n- US workspaces: https://email.us-west-1.api.bird.com\n\n## Data Retention\n\n- Events data is retained for 10 days\n- Aggregate reporting data is available through metrics or the app for up to 6 months\n\n## Event Types\n\nThe following types of events can be queried from the Events API:\n\n* Message Status Events:\n - `injection`: Message was accepted for delivery\n - `delivery`: Message was successfully delivered\n - `delay`: Message delivery was delayed\n - `bounce`: Message delivery failed\n - `spam_complaint`: Recipient marked message as spam\n - `out_of_band`: Message bounced after initial acceptance\n - `policy_rejection`: Message was rejected by policy\n - `generation_failure`: Message generation failed\n - `generation_rejection`: Message was rejected during generation\n\n* Recipient Engagement Events:\n - `open`: Message was opened\n - `initial_open`: First time message was opened\n - `click`: Link in message was clicked\n - `initial_click`: First time a link was clicked\n - `amp_click`: Link in AMP version was clicked\n - `amp_open`: AMP version was opened\n\n## Keyword Searching\n\nSome filter parameters support keyword searching, allowing filtering without precise values and multiple values without listing each one.\nKeywords are determined by natural breaks in phrases by spaces, dashes, underscores, and in special cases periods.\nThe following filters support keyword searching:\n- `campaigns`\n- `ip_pools`\n- `reasons`\n- `recipient_domains`\n- `sending_domains`\n- `subjects`\n- `mailbox_providers`\n- `mailbox_provider_regions`\n\n## Pagination\n\nThe Events API supports pagination for queries with larger result sets. Pagination is done through the use of the `cursor` and `per_page` query parameters.\nThe `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.\n\nTo 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.\nIn 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,\n`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.\n\nOnce 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,\nas well as any other filters you supplied with the original request.\n\nIn the following examples, to retrieve the first page, we use the `initial` value for the `cursor` query parameter. Then use the `cursor` value from\nthe `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,\nat which point the `links` object will not have a `next` key, and no further additional requests are necessary.\n\nIf your result set is less than one page of data, then the `links` object will not have a `next` key.\n\n**Note:** Pagination requests count towards the number of requests allowed by rate limiting, the same as non-paginated requests.\n"}],"servers":[{"url":"https://email.eu-west-1.api.bird.com/api","description":"Production endpoint for EU workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}},{"url":"https://email.us-west-1.api.bird.com/api","description":"Production endpoint for US workspaces","variables":{"protocol":{"enum":["https"],"default":"https","description":"Protocol for API communication"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key for authentication. Format: `AccessKey ` or `Bearer `.\n"}},"schemas":{"EventsResponse":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/Event"}},"total_count":{"type":"integer"},"links":{"$ref":"#/components/schemas/PaginationLinks"}}},"Event":{"required":["message_id","timestamp","type"],"type":"object","properties":{"type":{"type":"string","description":"Type of the message event","enum":["injection","delivery","delay","bounce","spam_complaint","out_of_band","policy_rejection","generation_failure","generation_rejection","open","initial_open","click","initial_click","amp_click","amp_open"]},"timestamp":{"type":"string","description":"Time when the event occurred","format":"date-time"},"message_id":{"type":"string","description":"Unique identifier for the message"},"campaign_id":{"type":"string","description":"Campaign ID associated with the message"},"injection":{"type":"object","properties":{"sending_ip":{"type":"string","description":"IP address used for sending"},"message_size":{"type":"integer","description":"Size of the message in bytes"}},"description":"Details about message injection (present for injection events)"},"delivery":{"type":"object","properties":{"delivery_time":{"type":"string","description":"Time of successful delivery","format":"date-time"},"destination_ip":{"type":"string","description":"IP address of receiving server"},"attempt_num":{"type":"integer","description":"Delivery attempt number"}},"description":"Details about message delivery (present for delivery events)"},"bounce":{"type":"object","properties":{"bounce_class":{"type":"integer","description":"Classification code for the bounce"},"error_code":{"type":"string","description":"SMTP error code"},"diagnostic_code":{"type":"string","description":"Extended bounce diagnostic"}},"description":"Details about message bounce (present for bounce events)"},"click":{"type":"object","properties":{"target_link_url":{"type":"string","description":"URL that was clicked"},"user_agent":{"type":"string","description":"User agent of the clicking client"},"geo_ip":{"$ref":"#/components/schemas/GeoIP"}},"description":"Details about link clicks (present for click events)"},"open":{"type":"object","properties":{"user_agent":{"type":"string","description":"User agent of the opening client"},"geo_ip":{"$ref":"#/components/schemas/GeoIP"}},"description":"Details about message opens (present for open events)"},"rcpt_to":{"type":"string","description":"Recipient email address","format":"email"},"raw_rcpt_to":{"type":"string","description":"Original recipient address from the SMTP transaction"},"rcpt_meta":{"type":"object","properties":{},"description":"Metadata specific to this recipient"},"transmission_id":{"type":"string","description":"ID of the transmission that generated this event"},"ip_pool":{"type":"string","description":"Name of the IP pool used for sending"},"sending_domain":{"type":"string","description":"Domain used to send the message"},"error_code":{"type":"string","description":"Error code if the event represents a failure"},"error_message":{"type":"string","description":"Detailed error message if the event represents a failure"}}},"GeoIP":{"type":"object","properties":{"country":{"type":"string","description":"Two-letter ISO 3166-1 alpha-2 country code"},"region":{"type":"string","description":"Region or state name"},"city":{"type":"string","description":"City name"},"latitude":{"type":"number","description":"Latitude coordinate","format":"float"},"longitude":{"type":"number","description":"Longitude coordinate","format":"float"},"zip":{"type":"string","description":"Postal or ZIP code"},"continent":{"type":"string","description":"Two-letter continent code","enum":["AF","AN","AS","EU","NA","OC","SA"]}},"description":"Geographical information derived from the IP address"},"PaginationLinks":{"type":"object","properties":{"first":{"type":"string","description":"URL for the first page of results"},"previous":{"type":"string","description":"URL for the previous page of results, omitted for first page"},"next":{"type":"string","description":"URL for the next page of results, omitted for last page"},"last":{"type":"string","description":"URL for the last page of results"}},"description":"Links for navigating paginated results"},"Error":{"required":["errors"],"type":"object","properties":{"errors":{"type":"array","items":{"required":["code","message"],"type":"object","properties":{"message":{"type":"string","description":"Human readable error message"},"code":{"type":"string","description":"Machine readable error code"},"description":{"type":"string","description":"Detailed error description"}}}}}}}},"paths":{"/workspaces/{workspaceId}/reach/events/message":{"get":{"tags":["Events"],"summary":"Search Message Events","description":"Returns message events matching the filtered search.\nData retention: 10 days for events, 6 months for aggregate reporting.\n\n**Note:** Maximum URI length is 4096 characters.\n","parameters":[{"name":"workspaceId","in":"path","description":"The ID of the workspace","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"from","in":"query","description":"Start datetime (`YYYY-MM-DDTHH:MM:ssZ`), inclusive. Value should be in UTC. Default is 24 hours ago.","schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","description":"End datetime (`YYYY-MM-DDTHH:MM:ssZ`), exclusive. Value should be in UTC. Default is 1 minute ago.","schema":{"type":"string","format":"date-time"}},{"name":"cursor","in":"query","description":"Results cursor for pagination. Used in conjunction with the `per_page` parameter. See the [Pagination](#pagination) section for more information.","schema":{"type":"string","default":"initial"}},{"name":"per_page","in":"query","description":"Results per page","schema":{"maximum":10000,"minimum":1,"type":"integer","default":1000}},{"name":"delimiter","in":"query","description":"Specifies the delimiter for query parameter lists","schema":{"type":"string","default":","}},{"name":"event_ids","in":"query","description":"Comma delimited list of event IDs to search","schema":{"type":"string"}},{"name":"events","in":"query","description":"Comma delimited list of event types to search","schema":{"type":"string","default":"all event types"}},{"name":"recipients","in":"query","description":"Comma delimited list of recipients to search","schema":{"type":"string"}},{"name":"recipient_domains","in":"query","description":"Comma delimited list of recipient domains to search. Supports keyword searching by domain segment","schema":{"type":"string"}},{"name":"from_addresses","in":"query","description":"Comma delimited list of friendly from addresses to search","schema":{"type":"string"}},{"name":"sending_domains","in":"query","description":"Comma delimited list of sending domains to search. Supports keyword searching by domain segment","schema":{"type":"string"}},{"name":"subjects","in":"query","description":"Comma delimited list of subject lines from the email header to search. Supports keyword searching","schema":{"type":"string"}},{"name":"bounce_classes","in":"query","description":"Comma delimited list of bounce classification codes to search. See the [Bounce Classification Codes](https://support.sparkpost.com/docs/deliverability/bounce-classification-codes) documentation for more information.","schema":{"type":"string"}},{"name":"reasons","in":"query","description":"Comma delimited list of bounce/failure/rejection reasons to search. Supports keyword searching","schema":{"type":"string"}},{"name":"campaigns","in":"query","description":"Comma delimited list of campaign IDs to search. Supports keyword searching","schema":{"type":"string"}},{"name":"sending_ips","in":"query","description":"Comma delimited list of sending IP addresses to search","schema":{"type":"string"}},{"name":"ip_pools","in":"query","description":"Comma delimited list of IP pool IDs to search. Supports keyword searching","schema":{"type":"string"}},{"name":"subaccounts","in":"query","description":"Comma delimited list of subaccount IDs to search","schema":{"type":"string"}},{"name":"messages","in":"query","description":"Comma delimited list of message IDs to search","schema":{"type":"string"}},{"name":"transmissions","in":"query","description":"Comma delimited list of transmission IDs to search","schema":{"type":"string"}},{"name":"mailbox_providers","in":"query","description":"Comma delimited list of mailbox providers to search. Supports keyword searching","schema":{"type":"string"}},{"name":"mailbox_provider_regions","in":"query","description":"Comma delimited list of mailbox provider regions to search. Supports keyword searching","schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully retrieved events","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventsResponse"}}}},"400":{"description":"Request validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}} ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.bird.com/api/email-api/events.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.