# 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.<br>

```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 API","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","type":"object","properties":{"success":{"type":"boolean"},"errors":{"type":"array","items":{"type":"string"}}}},"ErrorResponse":{"type":"object","properties":{"success":{"type":"boolean"},"errors":{"type":"array","items":{"type":"string"}}}},"RateLimitExceededResponse":{"title":"RateLimitExceededResponse","type":"object","properties":{"success":{"type":"boolean"},"errors":{"type":"array","items":{"type":"string"}}}}},"responses":{"BAD_REQUEST":{"description":"Bad request - invalid parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequest"}}}},"Unauthorized":{"description":"Unauthorized. Check your API credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"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 API","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}}},"ErrorResponse":{"type":"object","properties":{"success":{"type":"boolean"},"errors":{"type":"array","items":{"type":"string"}}}},"RateLimitExceededResponse":{"title":"RateLimitExceededResponse","type":"object","properties":{"success":{"type":"boolean"},"errors":{"type":"array","items":{"type":"string"}}}}},"responses":{"Unauthorized":{"description":"Unauthorized. Check your API credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"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"}}}}}}
```