> For the complete documentation index, see [llms.txt](https://docs.mailtrap.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mailtrap.io/developers/email-sending/email-logs/list-email-logs.md).

# List email logs

Returns a paginated list of email logs (messages) for the account. Results are restricted to 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 domains, suppressions, tracking opt-outs, 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"}},"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"},"domain_id":{"$ref":"#/components/schemas/FilterDomainId"},"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"}}]}}},"FilterDomainId":{"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},"rfc_message_id":{"type":"string","nullable":true,"description":"Value of the RFC 5322 `Message-ID` header."},"in_reply_to":{"type":"string","nullable":true,"description":"Value of the RFC 5322 `In-Reply-To` header."},"references":{"type":"array","items":{"type":"string"},"description":"Values of the RFC 5322 `References` header."},"thread_id":{"type":"string","nullable":true,"description":"ID of the inbound thread this message belongs to, or null if\nthe message is not part of one. Use it with the Inbound\nThreads endpoints to fetch the full conversation.\n"},"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"]},"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/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 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":[{"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"}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.mailtrap.io/developers/email-sending/email-logs/list-email-logs.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.