List emails

Search and page through synced emails across accounts and folders.

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.

Filters

All filters are optional and combine with AND.

account_id · string

Emails of one account (acc_…). Without it, all accounts.

folder · string

A folder’s fld_… id, its provider id, or a role (INBOX, SENT, ARCHIVE, …).

role · 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.

from · string

Sender address (exact, case-insensitive).

to · string

A recipient address (to, cc or bcc).

any_email · string

Sender or any recipient: everything exchanged with this person.

thread_id · string

All emails of a conversation.

unread · boolean

true for unread only, false for read only.

starred · boolean

Flagged (IMAP) or starred (Gmail) emails.

has_attachments · boolean

Emails with attachments (inline images count).

subject · string

Subject contains (case-insensitive).

before · date-time

Dated before this time (ISO 8601).

after · date-time

Dated after this time.

include_headers · boolean · default: "false"

Add every header of each email.

limit · integer · default: "50"

1 to 250.

cursor · string

From the previous page.

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

Response

{
  "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": "[e-mail]" },
      "to_attendees": [{ "display_name": "", "identifier": "[e-mail]" }],
      "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, bodies included. When has_more is true, pass cursor back, with the same filters, to get the next page.

Examples

Unread emails in the inbox

GET /api/v1/emails?account_id=acc_…&folder=INBOX&unread=true

Everything exchanged with one person

GET /api/v1/emails?account_id=acc_…&any_email=[e-mail]

A whole conversation

GET /api/v1/emails?thread_id=1a11078796ab3f43

Sent last week, with attachments

GET /api/v1/emails?account_id=acc_…&role=SENT&has_attachments=true&after=2026-09-29T00:00:00Z