Retrieve an email

curl "$EE_URL/api/v1/emails/email_94a0d77db739407e932c3b97fef44aac?include_headers=true" \
  -H "X-API-KEY: $EE_KEY"

include_headers=true adds the full list of headers. Emails of a removed account return 404, and so does an id that isn’t an email_… id.

The email object

string

Email. Drafts have Draft (see Drafts).

string

The engine’s email_… id. Stays the same when the email moves between folders.

string

The account it belongs to (acc_…).

string

The provider’s id for this message.

string

The Message-ID header, without angle brackets.

string

The conversation it belongs to. See Replies and threads.

date-time

When it was sent (the Date header), or received when that’s missing.

string

The start of the text, for previews.

string

HTML. For text-only emails, the text wrapped in HTML.

string

The plain-text version.

attendee

{ display_name, identifier }.

attendee[]

Recipients. bcc_attendees is only known for emails this account sent.

object | null

The email this one answers: { "message_id": "…", "id": "email_…" }. id is set when the account has that email, otherwise null.

string[]

The References header: the conversation’s earlier Message-IDs.

string[]

The folder it’s in. Over IMAP, Gmail shows each label as a folder, so an email with several labels is synced once per label (see Gmail).

string[]

The same folders, by fld_… id.

string

The main role: INBOX, SENT, DRAFTS, TRASH, SPAM, ARCHIVE or UNKNOWN.

boolean

Flagged in IMAP, starred in Gmail.

boolean

object[]

Each { id, name, extension, size, mime, cid, inline }. inline images are referenced from the HTML by cid. Download with the attachment endpoint.

integer

Message size in bytes.

string

api when the email was sent through this API (including drafts sent through the API), otherwise external.

string | null

The trk_… id when open and click tracking is on for this email, otherwise null.

object[]

With include_headers=true: every header as { name, value }.

Example

{
  "object": "Email",
  "id": "email_94a0d77db739407e932c3b97fef44aac",
  "account_id": "acc_ba1fa6938d8548298e8ce62e4b4b4e99",
  "provider_id": "1784129533:4821:INBOX",
  "message_id": "11fb30c561954dd39462f523c0c0282d@mail.gmail.com",
  "thread_id": "11fb30c561954dd39462f523c0c0282d@mail.gmail.com",
  "date": "2026-10-06T09:06:21Z",
  "subject": "Re: Quarterly report",
  "snippet": "Thanks, the numbers look good.",
  "body": "<p>Thanks, the numbers look good.</p>",
  "body_plain": "Thanks, the numbers look good.",
  "from_attendee": { "display_name": "Ana Lee", "identifier": "ana@acme.com" },
  "to_attendees": [{ "display_name": "Bob Stone", "identifier": "bob@example.com" }],
  "cc_attendees": [],
  "bcc_attendees": [],
  "reply_to_attendees": [],
  "in_reply_to": { "message_id": "CAKs9P1x@mail.example.com", "id": "email_5b1e9a2c3d4f4e6a8b7c0d1e2f3a4b5c" },
  "references": ["CAKs9P1x@mail.example.com"],
  "folders": ["SENT"],
  "folder_ids": ["fld_77c0a1b2c3d44e5f8a9b0c1d2e3f4a5b"],
  "role": "SENT",
  "unread": false,
  "starred": false,
  "has_attachments": true,
  "attachments": [{ "id": "att_6f2e8c1a0d4b4f7e9a512c3b8d7e1f00", "name": "notes.txt", "extension": "txt", "size": 23, "mime": "text/plain", "cid": null, "inline": false }],
  "size": 4096,
  "origin": "api",
  "tracking_id": null
}

Emails are a synced copy. When the user changes something in Gmail or their email app directly, the engine updates the email and sends a webhook (email.update, or email.delete when it’s deleted for good).

Getting started

Accounts

Emails

Webhooks

Reference

The email object

Example

​The email object

​Example

The email object

Example