Skip to content

Read mail

These need Read on the mailbox. A key only ever sees the mailboxes it has Read on.

GET /api/v1/messages, newest first.

Query What it does
mailbox Only this address. Without it, every mailbox the key can read.
folder inbox (default), sent, archive, spam, trash or all.
unread=true Only unread messages.
since Only messages after this date: ISO 8601 or epoch milliseconds.
limit 1 to 100, default 25.
Terminal window
curl "https://mail.example.com/api/v1/messages?mailbox=support@example.com&unread=true" \
-H "Authorization: Bearer $GENTLEMAIL_KEY"

Each item is a message summary: id, thread_id, mailbox, folder, direction, from, to, cc, subject, date, snippet, is_read, is_starred, attachments and url.

GET /api/v1/messages/:id returns the summary plus text (up to 200,000 characters, with text_truncated) and html, the message exactly as received.

POST /api/v1/messages/:id with { "action": "…" }, one of read, unread, star, unstar, archive, trash, spam or inbox.

Terminal window
curl -X POST https://mail.example.com/api/v1/messages/$ID \
-H "Authorization: Bearer $GENTLEMAIL_KEY" \
-H "Content-Type: application/json" \
-d '{ "action": "archive" }'

GET /api/v1/attachments/:id returns the file with its content type, as a download. Each attachment in a message or a webhook event has its own url.