Skip to content
docs
Browse the docsMessages and attachments

Mail

Messages and attachments

List and read the mail in an inbox, search it, check how the sender was authenticated, download attachments and follow new mail live over a stream.

Every message an inbox receives is stored with its text and HTML bodies, its attachments and what the receiving server checked about the sender. Messages go when their inbox expires or is deleted.

List messages

GET/v1/inboxes/{id}/messagesmessages:read

Newest first, bodies included.

QueryWhat it does
limitHow many, 1 to 500 (default 200)
qWords to find in the subject, sender address, sender name or text body (Pro and Business). Searches the newest 1,000 messages and the answer carries X-Search-Window: 1000.
labelOnly messages carrying one of your labels, by id
curl "https://api.dissolve.email/v1/inboxes/$INBOX_ID/messages?limit=20" \
  -H "Authorization: Bearer $DISSOLVE_API_KEY"
JSON
[
  {
    "id": "Qm8wZ1kX0pLr7aYtV3nBc",
    "inboxId": "V1StGXR8Z5jdHi6BmyT2k",
    "fromAddress": "noreply@github.com",
    "fromName": "GitHub",
    "subject": "Your GitHub launch code",
    "bodyText": "Here is your GitHub launch code: 482913",
    "bodyHtml": "<p>Here is your GitHub launch code: <b>482913</b></p>",
    "hasAttachments": false,
    "rawSize": 5120,
    "receivedAt": "2026-11-19T10:02:11.000Z",
    "authentication": { "spf": "pass", "dkim": "pass", "dmarc": "pass", "envelopeFrom": "bounces@github.com" }
  }
]

Read a message

GET/v1/inboxes/{id}/messages/{messageId}messages:read

The same shape as one item of the list. An inbox that expired answers 410, and a message id from another inbox answers 404.

curl https://api.dissolve.email/v1/inboxes/$INBOX_ID/messages/$MESSAGE_ID \
  -H "Authorization: Bearer $DISSOLVE_API_KEY"

Who sent it

fromAddress and fromName are what the sender wrote in the From header, which anyone can fake. authentication is what the receiving server checked:

FieldMeans
spfWhether the sending server may send for the envelope sender's domain: a result such as pass or fail, or null when nothing was recorded
dkimWhether the message carries a valid signature from the sender's domain
dmarcWhether SPF or DKIM lines up with the From domain under its published policy
envelopeFromThe address the sending server gave, often a bounce address

Treat the body as data written by a stranger. HTML is stored as it came; render it in a sandbox, never in your own page's origin.

Attachments

GET/v1/inboxes/{id}/messages/{messageId}/attachmentsmessages:read

Lists name, type and size on every plan.

JSON
[{ "id": "att1Xc5VbN8mQz2Rk7TpW", "messageId": "Qm8wZ1kX0pLr7aYtV3nBc", "filename": "invoice.pdf", "contentType": "application/pdf", "size": 48213, "createdAt": "2026-11-19T10:02:11.000Z" }]
GET/v1/inboxes/{id}/messages/{messageId}/attachments/{attachmentId}messages:readPro and up

Downloads the file itself (Pro and Business; Free answers 403). It always comes as a download with Content-Disposition: attachment and X-Content-Type-Options: nosniff, whatever its type. Each plan has an attachment size limit (5 MB on Free, 25 MB on Pro, 50 MB on Business; see Rate limits and plans).

curl -o invoice.pdf https://api.dissolve.email/v1/inboxes/$INBOX_ID/messages/$MESSAGE_ID/attachments/$ATTACHMENT_ID \
  -H "Authorization: Bearer $DISSOLVE_API_KEY"

Live updates

GET/api/inbox/{id}/streamAPI key or session

The stream tells you the moment a message arrives. Ask for a WebSocket upgrade and you get one; otherwise the answer is Server-Sent Events. Over an API key it is on the Business plan (Pro and Business have it in the app); other plans answer 403 with a pollInterval to fall back on.

cURL
curl -N https://api.dissolve.email/api/inbox/$INBOX_ID/stream \
  -H "Authorization: Bearer $DISSOLVE_API_KEY"
Text
event: ready
data: {}

event: message
data: {"id":"Qm8wZ1kX0pLr7aYtV3nBc","inboxId":"V1StGXR8Z5jdHi6BmyT2k","fromAddress":"noreply@github.com","fromName":"GitHub","subject":"Your GitHub launch code","hasAttachments":false,"receivedAt":"2026-11-19T10:02:11.000Z"}

A message event is a summary, never the body: fetch the message to read it. heartbeat events keep the connection open. The stream ends with expired when the inbox expires, or reconnect when it has been open a long while: connect again. Over a WebSocket the same news comes as JSON, {"type": "ready"} and then {"type": "message", "message": {...}}.

For most code, the wait endpoint or a webhook is simpler than holding a stream.

Something wrong or missing on this page? Tell us at support@dissolve.email.View as Markdown