Messages
List a mailbox's messages and read one back as structured content.
Messages live inside a mailbox. Listing them gives you metadata and a snippet; reading one gives you decoded headers, bodies, and attachment references.
Paths are relative to https://api.open.email/api/v1, and every request carries
a bearer credential — see Authentication.
List messages
GET /mailboxes/{mailboxId}/messages
curl "$API/mailboxes/$MAILBOX_ID/messages?limit=25" \
-H "Authorization: Bearer $TOKEN"Newest first by default, with cursor pagination. You can restrict to one label,
filter on flags, and switch state to expunged to list the trash instead.
Hold order constant across a crawl. Cursors do not encode direction, so
reusing one under the opposite order silently yields a differently-windowed
page rather than an error.
{
"messages": [
{
"id": "msg_...",
"subject": "Hello from OpenEmail",
"snippet": "Sent over HTTP.",
"labels": [{ "name": "INBOX", "uid": 1, "uidValidity": 1 }],
"receivedAt": 1786000000,
"threadId": "thr_...",
"uid": 1
}
],
"nextCursor": "..."
}receivedAt and sentAt are Unix timestamps. Each entry in labels carries
its own uid — labels are how OpenEmail models folders, and IMAP requires a
per-folder UID.
Read a message
GET /mailboxes/{mailboxId}/messages/{messageId}/content
curl "$API/mailboxes/$MAILBOX_ID/messages/$MESSAGE_ID/content" \
-H "Authorization: Bearer $TOKEN"Returns the message decoded and structured — you do not have to parse MIME yourself:
{
"headers": {
"from": [{ "email": "you@example.com", "name": null }],
"subject": "Hello from OpenEmail",
"date": 1786000000
},
"text": "Sent over HTTP.",
"html": null,
"attachments": []
}Attachments come back as references, not bytes. Each carries a section — the
MIME part identifier you pass to the message parts endpoint to stream it — plus
the filename, content type and size the sender declared. One field is easy to
miss: degraded marks a part whose metadata could not be read in full, so
treat its filename and size as unreliable rather than absent.
Two failures are terminal for a given message, and worth handling as such
rather than retrying: 413 message_too_large when the blob exceeds the parse
ceiling, and 422 unparseable_message or message_too_complex. The content
endpoint will not succeed on a later attempt for either. Fall back to streaming
the raw MIME blob instead.
The endpoint also honours If-None-Match against the content ETag, so a poller
can take a 304 instead of the body.
In the TypeScript SDK
Each call above is a method of the TypeScript SDK:
messages.listisGET /mailboxes/{mailboxId}/messages; iterated withfor await, it is every message of every page (Listings).messages.getContentisGET /mailboxes/{mailboxId}/messages/{messageId}/content, and itsifNoneMatchoption takes the content's ETag (conditional reads).