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.
| Query | What it does |
|---|---|
limit | How many, 1 to 500 (default 200) |
q | Words 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. |
label | Only 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"import { Dissolve } from '@dissolve-email/sdk';
const client = new Dissolve();
const messages = await client.v1.listMessages(inboxId);
for (const message of messages) console.log(message.subject, message.fromAddress);import os, requests
HEADERS = {"Authorization": f"Bearer {os.environ['DISSOLVE_API_KEY']}"}
messages = requests.get(
f"https://api.dissolve.email/v1/inboxes/{inbox_id}/messages",
params={"limit": 20},
headers=HEADERS,
).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"const message = await client.v1.getMessage(inboxId, messageId);
console.log(message.bodyText);message = requests.get(
f"https://api.dissolve.email/v1/inboxes/{inbox_id}/messages/{message_id}",
headers=HEADERS,
).json()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:
| Field | Means |
|---|---|
spf | Whether the sending server may send for the envelope sender's domain: a result such as pass or fail, or null when nothing was recorded |
dkim | Whether the message carries a valid signature from the sender's domain |
dmarc | Whether SPF or DKIM lines up with the From domain under its published policy |
envelopeFrom | The 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.
[{ "id": "att1Xc5VbN8mQz2Rk7TpW", "messageId": "Qm8wZ1kX0pLr7aYtV3nBc", "filename": "invoice.pdf", "contentType": "application/pdf", "size": 48213, "createdAt": "2026-11-19T10:02:11.000Z" }]/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"const response = await client.v1.downloadAttachment(inboxId, messageId, attachmentId);
const bytes = new Uint8Array(await response.arrayBuffer());response = requests.get(
f"https://api.dissolve.email/v1/inboxes/{inbox_id}/messages/{message_id}/attachments/{attachment_id}",
headers=HEADERS,
)
open("invoice.pdf", "wb").write(response.content)Live updates
/api/inbox/{id}/streamAPI key or sessionThe 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 -N https://api.dissolve.email/api/inbox/$INBOX_ID/stream \
-H "Authorization: Bearer $DISSOLVE_API_KEY"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