# Email Logs
List and retrieve email sending logs for the account.
## List email logs
> Returns a paginated list of email logs (messages) for the account.\
> Results are restricted to sending domains the authenticated token has access to.\
> Invalid or unknown filters are ignored. Results are ordered by sent\_at descending.
```json
{"openapi":"3.1.0","info":{"title":"Email Sending","version":"2.0.0"},"tags":[{"name":"email-logs","description":"List and retrieve email sending logs for the account."}],"servers":[{"description":"Mailtrap account API (`mailtrap.io`) for sending domains, suppressions, stats, and email logs.\nError JSON matches other account endpoints (`error` or string `errors`), not the `send.api` / `bulk.api` sending shape (`success` + `errors` array).\n","url":"https://mailtrap.io"}],"security":[{"HeaderAuth":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"HeaderAuth":{"type":"apiKey","description":"API token in Api-Token header","in":"header","name":"Api-Token"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token authentication"}},"parameters":{"account_id":{"name":"account_id","in":"path","required":true,"description":"Account ID","schema":{"type":"integer"}}},"schemas":{"EmailLogsListFilters":{"type":"object","description":"Key-value map of filter name to filter spec. Each spec has operator and optional value.\nDate range uses sent_after / sent_before at top level of filters (see below).\nIn query params, array values use bracket notation: `filters[field][value][]=a&filters[field][value][]=b`.\n","properties":{"sent_after":{"type":"string","format":"date-time","description":"Start of sent-at range (ISO 8601). Must be before or equal to sent_before."},"sent_before":{"type":"string","format":"date-time","description":"End of sent-at range (ISO 8601). Must be after or equal to sent_after."},"to":{"$ref":"#/components/schemas/FilterTo"},"from":{"$ref":"#/components/schemas/FilterFrom"},"subject":{"$ref":"#/components/schemas/FilterSubject"},"status":{"$ref":"#/components/schemas/FilterStatus"},"events":{"$ref":"#/components/schemas/FilterEvents"},"clicks_count":{"$ref":"#/components/schemas/FilterClicksCount"},"opens_count":{"$ref":"#/components/schemas/FilterOpensCount"},"client_ip":{"$ref":"#/components/schemas/FilterClientIp"},"sending_ip":{"$ref":"#/components/schemas/FilterSendingIp"},"email_service_provider_response":{"$ref":"#/components/schemas/FilterEmailServiceProviderResponse"},"email_service_provider":{"$ref":"#/components/schemas/FilterEmailServiceProvider"},"recipient_mx":{"$ref":"#/components/schemas/FilterRecipientMx"},"category":{"$ref":"#/components/schemas/FilterCategory"},"sending_domain_id":{"$ref":"#/components/schemas/FilterSendingDomainId"},"sending_stream":{"$ref":"#/components/schemas/FilterSendingStream"}}},"FilterTo":{"oneOf":[{"$ref":"#/components/schemas/FilterCiEqualString"},{"$ref":"#/components/schemas/FilterCiContainString"}],"discriminator":{"propertyName":"operator","mapping":{"ci_equal":"#/components/schemas/FilterCiEqualString","ci_not_equal":"#/components/schemas/FilterCiEqualString","ci_contain":"#/components/schemas/FilterCiContainString","ci_not_contain":"#/components/schemas/FilterCiContainString"}}},"FilterCiEqualString":{"type":"object","required":["operator","value"],"properties":{"operator":{"type":"string","enum":["ci_equal","ci_not_equal"],"description":"ci_* = case-insensitive"},"value":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}}},"FilterCiContainString":{"type":"object","required":["operator","value"],"properties":{"operator":{"type":"string","enum":["ci_contain","ci_not_contain"],"description":"ci_* = case-insensitive"},"value":{"type":"string"}}},"FilterFrom":{"oneOf":[{"$ref":"#/components/schemas/FilterCiEqualString"},{"$ref":"#/components/schemas/FilterCiContainString"}],"discriminator":{"propertyName":"operator","mapping":{"ci_equal":"#/components/schemas/FilterCiEqualString","ci_not_equal":"#/components/schemas/FilterCiEqualString","ci_contain":"#/components/schemas/FilterCiContainString","ci_not_contain":"#/components/schemas/FilterCiContainString"}}},"FilterSubject":{"oneOf":[{"$ref":"#/components/schemas/FilterCiEqualString"},{"$ref":"#/components/schemas/FilterCiContainString"},{"$ref":"#/components/schemas/FilterEmptyString"}],"discriminator":{"propertyName":"operator","mapping":{"ci_equal":"#/components/schemas/FilterCiEqualString","ci_not_equal":"#/components/schemas/FilterCiEqualString","ci_contain":"#/components/schemas/FilterCiContainString","ci_not_contain":"#/components/schemas/FilterCiContainString","empty":"#/components/schemas/FilterEmptyString","not_empty":"#/components/schemas/FilterEmptyString"}}},"FilterEmptyString":{"type":"object","required":["operator"],"properties":{"operator":{"type":"string","enum":["empty","not_empty"]}}},"FilterStatus":{"type":"object","required":["operator","value"],"properties":{"operator":{"type":"string","enum":["equal","not_equal"]},"value":{"oneOf":[{"type":"string","enum":["delivered","not_delivered","enqueued","opted_out"]},{"type":"array","items":{"type":"string","enum":["delivered","not_delivered","enqueued","opted_out"]}}]}}},"FilterEvents":{"type":"object","required":["operator","value"],"properties":{"operator":{"type":"string","enum":["include_event","not_include_event"]},"value":{"oneOf":[{"type":"string","enum":["delivery","open","click","bounce","spam","unsubscribe","soft_bounce","reject","suspension"]},{"type":"array","items":{"type":"string","enum":["delivery","open","click","bounce","spam","unsubscribe","soft_bounce","reject","suspension"]}}]}}},"FilterClicksCount":{"type":"object","required":["operator","value"],"properties":{"operator":{"type":"string","enum":["equal","greater_than","less_than"]},"value":{"type":"integer"}}},"FilterOpensCount":{"type":"object","required":["operator","value"],"properties":{"operator":{"type":"string","enum":["equal","greater_than","less_than"]},"value":{"type":"integer"}}},"FilterClientIp":{"oneOf":[{"$ref":"#/components/schemas/FilterEqualString"},{"$ref":"#/components/schemas/FilterContainString"}],"discriminator":{"propertyName":"operator","mapping":{"equal":"#/components/schemas/FilterEqualString","not_equal":"#/components/schemas/FilterEqualString","contain":"#/components/schemas/FilterContainString","not_contain":"#/components/schemas/FilterContainString"}}},"FilterEqualString":{"type":"object","required":["operator","value"],"properties":{"operator":{"type":"string","enum":["equal","not_equal"]},"value":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}}},"FilterContainString":{"type":"object","required":["operator","value"],"properties":{"operator":{"type":"string","enum":["contain","not_contain"]},"value":{"type":"string"}}},"FilterSendingIp":{"oneOf":[{"$ref":"#/components/schemas/FilterEqualString"},{"$ref":"#/components/schemas/FilterContainString"}],"discriminator":{"propertyName":"operator","mapping":{"equal":"#/components/schemas/FilterEqualString","not_equal":"#/components/schemas/FilterEqualString","contain":"#/components/schemas/FilterContainString","not_contain":"#/components/schemas/FilterContainString"}}},"FilterEmailServiceProviderResponse":{"oneOf":[{"$ref":"#/components/schemas/FilterCiEqualString"},{"$ref":"#/components/schemas/FilterCiContainString"}],"discriminator":{"propertyName":"operator","mapping":{"ci_equal":"#/components/schemas/FilterCiEqualString","ci_not_equal":"#/components/schemas/FilterCiEqualString","ci_contain":"#/components/schemas/FilterCiContainString","ci_not_contain":"#/components/schemas/FilterCiContainString"}}},"FilterEmailServiceProvider":{"type":"object","required":["operator","value"],"properties":{"operator":{"type":"string","enum":["equal","not_equal"]},"value":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}}},"FilterRecipientMx":{"oneOf":[{"$ref":"#/components/schemas/FilterCiEqualString"},{"$ref":"#/components/schemas/FilterCiContainString"}],"discriminator":{"propertyName":"operator","mapping":{"ci_equal":"#/components/schemas/FilterCiEqualString","ci_not_equal":"#/components/schemas/FilterCiEqualString","ci_contain":"#/components/schemas/FilterCiContainString","ci_not_contain":"#/components/schemas/FilterCiContainString"}}},"FilterCategory":{"type":"object","required":["operator","value"],"properties":{"operator":{"type":"string","enum":["equal","not_equal"]},"value":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}}},"FilterSendingDomainId":{"type":"object","required":["operator","value"],"properties":{"operator":{"type":"string","enum":["equal","not_equal"]},"value":{"oneOf":[{"type":"integer"},{"type":"array","items":{"type":"integer"}}]}}},"FilterSendingStream":{"type":"object","required":["operator","value"],"properties":{"operator":{"type":"string","enum":["equal","not_equal"]},"value":{"oneOf":[{"type":"string","enum":["transactional","bulk"]},{"type":"array","items":{"type":"string","enum":["transactional","bulk"]}}]}}},"EmailLogsListResponse":{"type":"object","required":["messages","total_count","next_page_cursor"],"properties":{"messages":{"type":"array","items":{"type":"object","properties":{"message_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["delivered","not_delivered","enqueued","opted_out"]},"subject":{"type":"string","nullable":true},"from":{"type":"string"},"to":{"type":"string"},"sent_at":{"type":"string","format":"date-time"},"client_ip":{"type":"string","nullable":true},"category":{"type":"string","nullable":true},"custom_variables":{"type":"object"},"sending_stream":{"type":"string","enum":["transactional","bulk"]},"sending_domain_id":{"type":"integer"},"template_id":{"type":"integer","nullable":true},"template_variables":{"type":"object"},"opens_count":{"type":"integer"},"clicks_count":{"type":"integer"}}}},"total_count":{"type":"integer","description":"Total number of messages matching the filters (before pagination)."},"next_page_cursor":{"type":"string","format":"uuid","nullable":true,"description":"Message UUID to use as search_after for the next page. Null if no more pages."}}},"BadRequest":{"title":"BadRequestResponse","description":"Invalid parameters. Some endpoints return an empty body with HTTP 400; when present, a message may use an `error` field.\n","type":"object","properties":{"error":{"type":"string"}}},"UnauthenticatedResponse":{"title":"UnauthenticatedResponse","type":"object","properties":{"error":{"type":"string","description":"Error message"}}},"NotFoundResponse":{"title":"NotFoundResponse","type":"object","properties":{"error":{"type":"string","description":"Error message"}}},"RateLimitExceededResponse":{"title":"RateLimitExceededResponse","type":"object","properties":{"errors":{"type":"string","description":"Error message"}}}},"responses":{"BAD_REQUEST":{"description":"Bad request - invalid parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequest"}}}},"Unauthorized":{"description":"Returns unauthorized error message. Check your credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthenticatedResponse"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundResponse"}}}},"LIMIT_EXCEEDED":{"description":"Rate limit exceeded for the current account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitExceededResponse"}}}}}},"paths":{"/api/accounts/{account_id}/email_logs":{"get":{"operationId":"listEmailLogs","summary":"List email logs","description":"Returns a paginated list of email logs (messages) for the account.\nResults are restricted to sending domains the authenticated token has access to.\nInvalid or unknown filters are ignored. Results are ordered by sent_at descending.\n","tags":["email-logs"],"parameters":[{"$ref":"#/components/parameters/account_id"},{"name":"search_after","in":"query","description":"Cursor for the next page (message_id UUID from previous response next_page_cursor).","schema":{"type":"string","format":"uuid"}},{"name":"filters","in":"query","description":"Filter criteria (deep object). Pass as `filters[field][operator]` and `filters[field][value]`.\nWhen a filter accepts an array value, use bracket notation: `filters[field][value][]=item1&filters[field][value][]=item2`.\nDate range: use `filters[sent_after]` and `filters[sent_before]` (ISO 8601 strings).\nUnknown filters are ignored.\n","style":"deepObject","explode":true,"schema":{"$ref":"#/components/schemas/EmailLogsListFilters"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailLogsListResponse"}}}},"400":{"$ref":"#/components/responses/BAD_REQUEST"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/LIMIT_EXCEEDED"}}}}}}
```
## Get an email log message by ID
> Returns a single message by message UUID. Message must belong to the account and a sending domain the token can access.
```json
{"openapi":"3.1.0","info":{"title":"Email Sending","version":"2.0.0"},"tags":[{"name":"email-logs","description":"List and retrieve email sending logs for the account."}],"servers":[{"description":"Mailtrap account API (`mailtrap.io`) for sending domains, suppressions, stats, and email logs.\nError JSON matches other account endpoints (`error` or string `errors`), not the `send.api` / `bulk.api` sending shape (`success` + `errors` array).\n","url":"https://mailtrap.io"}],"security":[{"HeaderAuth":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"HeaderAuth":{"type":"apiKey","description":"API token in Api-Token header","in":"header","name":"Api-Token"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token authentication"}},"parameters":{"account_id":{"name":"account_id","in":"path","required":true,"description":"Account ID","schema":{"type":"integer"}},"sending_message_id":{"name":"sending_message_id","in":"path","required":true,"description":"Message UUID","schema":{"type":"string","format":"uuid"}}},"schemas":{"SendingMessage":{"type":"object","properties":{"message_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["delivered","not_delivered","enqueued","opted_out"]},"subject":{"type":"string","nullable":true},"from":{"type":"string"},"to":{"type":"string"},"sent_at":{"type":"string","format":"date-time"},"client_ip":{"type":"string","nullable":true},"category":{"type":"string","nullable":true},"custom_variables":{"type":"object"},"sending_stream":{"type":"string","enum":["transactional","bulk"]},"sending_domain_id":{"type":"integer"},"template_id":{"type":"integer","nullable":true},"template_variables":{"type":"object"},"opens_count":{"type":"integer"},"clicks_count":{"type":"integer"},"raw_message_url":{"type":"string","format":"uri","description":"Signed URL to download raw .eml message (temporary)."},"events":{"type":"array","items":{"$ref":"#/components/schemas/MessageEvent"}}}},"MessageEvent":{"description":"Event with type-specific details. Use event_type to determine which details schema applies.","discriminator":{"propertyName":"event_type","mapping":{"delivery":"#/components/schemas/MessageEventDelivery","open":"#/components/schemas/MessageEventOpen","click":"#/components/schemas/MessageEventClick","soft_bounce":"#/components/schemas/MessageEventBounce","bounce":"#/components/schemas/MessageEventBounce","spam":"#/components/schemas/MessageEventSpam","unsubscribe":"#/components/schemas/MessageEventUnsubscribe","suspension":"#/components/schemas/MessageEventReject","reject":"#/components/schemas/MessageEventReject"}},"oneOf":[{"$ref":"#/components/schemas/MessageEventDelivery"},{"$ref":"#/components/schemas/MessageEventOpen"},{"$ref":"#/components/schemas/MessageEventClick"},{"$ref":"#/components/schemas/MessageEventBounce"},{"$ref":"#/components/schemas/MessageEventSpam"},{"$ref":"#/components/schemas/MessageEventUnsubscribe"},{"$ref":"#/components/schemas/MessageEventReject"}]},"MessageEventDelivery":{"type":"object","required":["event_type","created_at","details"],"properties":{"event_type":{"type":"string","enum":["delivery"]},"created_at":{"type":"string","format":"date-time"},"details":{"$ref":"#/components/schemas/EventDetailsDelivery"}}},"EventDetailsDelivery":{"type":"object","description":"For event_type = delivery","additionalProperties":false,"properties":{"sending_ip":{"type":"string","nullable":true},"recipient_mx":{"type":"string","nullable":true},"email_service_provider":{"type":"string","nullable":true}}},"MessageEventOpen":{"type":"object","required":["event_type","created_at","details"],"properties":{"event_type":{"type":"string","enum":["open"]},"created_at":{"type":"string","format":"date-time"},"details":{"$ref":"#/components/schemas/EventDetailsOpen"}}},"EventDetailsOpen":{"type":"object","description":"For event_type = open","additionalProperties":false,"properties":{"web_ip_address":{"type":"string","nullable":true}}},"MessageEventClick":{"type":"object","required":["event_type","created_at","details"],"properties":{"event_type":{"type":"string","enum":["click"]},"created_at":{"type":"string","format":"date-time"},"details":{"$ref":"#/components/schemas/EventDetailsClick"}}},"EventDetailsClick":{"type":"object","description":"For event_type = click","additionalProperties":false,"properties":{"click_url":{"type":"string","nullable":true},"web_ip_address":{"type":"string","nullable":true}}},"MessageEventBounce":{"type":"object","required":["event_type","created_at","details"],"properties":{"event_type":{"type":"string","enum":["soft_bounce","bounce"]},"created_at":{"type":"string","format":"date-time"},"details":{"$ref":"#/components/schemas/EventDetailsBounce"}}},"EventDetailsBounce":{"type":"object","description":"For event_type = soft_bounce or bounce","additionalProperties":false,"properties":{"sending_ip":{"type":"string","nullable":true},"recipient_mx":{"type":"string","nullable":true},"email_service_provider":{"type":"string","nullable":true},"email_service_provider_status":{"type":"string","nullable":true},"email_service_provider_response":{"type":"string","nullable":true},"bounce_category":{"type":"string","nullable":true}}},"MessageEventSpam":{"type":"object","required":["event_type","created_at","details"],"properties":{"event_type":{"type":"string","enum":["spam"]},"created_at":{"type":"string","format":"date-time"},"details":{"$ref":"#/components/schemas/EventDetailsSpam"}}},"EventDetailsSpam":{"type":"object","description":"For event_type = spam","additionalProperties":false,"properties":{"spam_feedback_type":{"type":"string","nullable":true}}},"MessageEventUnsubscribe":{"type":"object","required":["event_type","created_at","details"],"properties":{"event_type":{"type":"string","enum":["unsubscribe"]},"created_at":{"type":"string","format":"date-time"},"details":{"$ref":"#/components/schemas/EventDetailsUnsubscribe"}}},"EventDetailsUnsubscribe":{"type":"object","description":"For event_type = unsubscribe","additionalProperties":false,"properties":{"web_ip_address":{"type":"string","nullable":true}}},"MessageEventReject":{"type":"object","required":["event_type","created_at","details"],"properties":{"event_type":{"type":"string","enum":["suspension","reject"]},"created_at":{"type":"string","format":"date-time"},"details":{"$ref":"#/components/schemas/EventDetailsReject"}}},"EventDetailsReject":{"type":"object","description":"For event_type = suspension or reject","additionalProperties":false,"properties":{"reject_reason":{"type":"string","nullable":true}}},"UnauthenticatedResponse":{"title":"UnauthenticatedResponse","type":"object","properties":{"error":{"type":"string","description":"Error message"}}},"NotFoundResponse":{"title":"NotFoundResponse","type":"object","properties":{"error":{"type":"string","description":"Error message"}}},"RateLimitExceededResponse":{"title":"RateLimitExceededResponse","type":"object","properties":{"errors":{"type":"string","description":"Error message"}}}},"responses":{"Unauthorized":{"description":"Returns unauthorized error message. Check your credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthenticatedResponse"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundResponse"}}}},"LIMIT_EXCEEDED":{"description":"Rate limit exceeded for the current account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitExceededResponse"}}}}}},"paths":{"/api/accounts/{account_id}/email_logs/{sending_message_id}":{"get":{"operationId":"getEmailLogMessage","summary":"Get an email log message by ID","description":"Returns a single message by message UUID. Message must belong to the account and a sending domain the token can access.","tags":["email-logs"],"parameters":[{"$ref":"#/components/parameters/account_id"},{"$ref":"#/components/parameters/sending_message_id"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendingMessage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/LIMIT_EXCEEDED"}}}}}}
```
---
# 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.mailtrap.io/developers/email-sending/email-logs.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.