> ## Documentation Index
> Fetch the complete documentation index at: https://pigeonpost-developer.27communication.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List emails

> Search and page through synced emails across accounts and folders.

```bash theme={null}
curl "$EE_URL/api/v1/emails?account_id=acc_ba1fa6938d8548298e8ce62e4b4b4e99&folder=INBOX&unread=true&limit=50" \
  -H "X-API-KEY: $EE_KEY"
```

Emails come **newest first** (by their `date`). Results are [paged with a cursor](/reference/pagination).

## Filters

All filters are optional and combine with AND.

<ParamField query="account_id" type="string">Emails of one account (`acc_…`). Without it, all accounts.</ParamField>
<ParamField query="folder" type="string">A folder's `fld_…` id, its provider id, or a role (`INBOX`, `SENT`, `ARCHIVE`, …).</ParamField>
<ParamField query="role" type="string">The email's main role, such as `INBOX` or `SENT`. An email you sent to yourself (in Inbox and Sent) matches only its main role.</ParamField>
<ParamField query="from" type="string">Sender address (exact, case-insensitive).</ParamField>
<ParamField query="to" type="string">A recipient address (to, cc or bcc).</ParamField>
<ParamField query="any_email" type="string">Sender or any recipient: everything exchanged with this person.</ParamField>
<ParamField query="thread_id" type="string">All emails of a conversation.</ParamField>
<ParamField query="unread" type="boolean">`true` for unread only, `false` for read only.</ParamField>
<ParamField query="starred" type="boolean">Flagged (IMAP) or starred (Gmail) emails.</ParamField>
<ParamField query="has_attachments" type="boolean">Emails with attachments (inline images count).</ParamField>
<ParamField query="subject" type="string">Subject contains (case-insensitive).</ParamField>
<ParamField query="before" type="date-time">Dated before this time (ISO 8601).</ParamField>
<ParamField query="after" type="date-time">Dated after this time.</ParamField>
<ParamField query="include_headers" type="boolean" default="false">Add every header of each email.</ParamField>
<ParamField query="limit" type="integer" default="50">1 to 250.</ParamField>
<ParamField query="cursor" type="string">From the previous page.</ParamField>

An `account_id` that isn't an `acc_…` id gets `400 errors/invalid_parameters`.

## Response

```json theme={null}
{
  "object": "Emails",
  "data": [
    {
      "object": "Email",
      "id": "email_94a0d77db739407e932c3b97fef44aac",
      "account_id": "acc_ba1fa6938d8548298e8ce62e4b4b4e99",
      "subject": "Quarterly report",
      "snippet": "Hi team, please find attached the…",
      "from_attendee": { "display_name": "Ana Lee", "identifier": "ana@example.com" },
      "to_attendees": [{ "display_name": "", "identifier": "sales@acme.com" }],
      "date": "2026-10-06T09:12:00Z",
      "folders": ["INBOX"],
      "folder_ids": ["fld_0b7e2d4c1a3f4e5b8c9d7f6e5d4c3b2a"],
      "role": "INBOX",
      "unread": true,
      "starred": false,
      "has_attachments": true,
      "attachments": [{ "id": "att_6f2e8c1a0d4b4f7e9a512c3b8d7e1f00", "name": "report.pdf", "extension": "pdf", "size": 182044, "mime": "application/pdf", "cid": null, "inline": false }],
      "origin": "external",
      "tracking_id": null,
      "…": "…"
    }
  ],
  "has_more": true,
  "cursor": "eyJkIjoiMjAyNi0xMC0wNlQwOToxMjowMFoiLCJpIjoiOTRhMGQ3N2QifQ"
}
```

Each item is a full [email object](/emails/retrieve), bodies included. When `has_more` is `true`, pass `cursor` back, with the same filters, to get the next page.

## Examples

<AccordionGroup>
  <Accordion title="Unread emails in the inbox">
    `GET /api/v1/emails?account_id=acc_…&folder=INBOX&unread=true`
  </Accordion>

  <Accordion title="Everything exchanged with one person">
    `GET /api/v1/emails?account_id=acc_…&any_email=ana@example.com`
  </Accordion>

  <Accordion title="A whole conversation">
    `GET /api/v1/emails?thread_id=1a11078796ab3f43`
  </Accordion>

  <Accordion title="Sent last week, with attachments">
    `GET /api/v1/emails?account_id=acc_…&role=SENT&has_attachments=true&after=2026-09-29T00:00:00Z`
  </Accordion>
</AccordionGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.