API reference
Messages API
Mail in an inbox and its attachments. Every messages endpoint with its scope, parameters, body and an example answer.
Base URL https://api.dissolve.email. Send an API key or OAuth access token as Authorization: Bearer <token> (Authentication); an OAuth token needs the scope on each endpoint. Errors follow one shape.
| Endpoint | Summary |
|---|---|
GET /v1/inboxes/{id}/messages | List messages |
GET /v1/inboxes/{id}/messages/{messageId} | Get a message |
GET /v1/inboxes/{id}/messages/{messageId}/attachments | List a message's attachments |
GET /v1/inboxes/{id}/messages/{messageId}/attachments/{attachmentId} | Download an attachment |
List messages
/v1/inboxes/{id}/messagesmessages:readMessages in the inbox, newest first, bodies included. Listing is held to five calls a minute per credential: to wait for mail, use GET /v1/inboxes/{id}/wait instead of polling. q searches the newest 1,000 messages (Pro and Business) and the answer carries X-Search-Window: 1000.
Path parameters
| Name | Description |
|---|---|
id | The message id. |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
limit | integer | no | How many messages to return. Default 200. 1 to 500. |
q | string | no | Words to find in the subject, sender or text body (Pro and Business). At most 100 characters. |
label | string | no | Only messages carrying this label id. |
curl "https://api.dissolve.email/v1/inboxes/$INBOX_ID/messages" \
-H "Authorization: Bearer $DISSOLVE_API_KEY"import { Dissolve } from '@dissolve-email/sdk';
const client = new Dissolve(); // reads DISSOLVE_API_KEY
const result = await client.v1.listMessages(inboxId);import os, requests
API_KEY = os.environ["DISSOLVE_API_KEY"]
response = requests.get(f"https://api.dissolve.email/v1/inboxes/{inbox_id}/messages", headers={"Authorization": f"Bearer {API_KEY}"})
print(response.json())Response 200
[
{
"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"
}
}
]Get a message
/v1/inboxes/{id}/messages/{messageId}messages:readOne message in full: text and HTML bodies, size, and what the receiving server checked (SPF, DKIM, DMARC and the envelope sender). The From header is the sender's own claim.
Path parameters
| Name | Description |
|---|---|
id | The message id. |
messageId | The message id. |
curl "https://api.dissolve.email/v1/inboxes/$INBOX_ID/messages/$MESSAGE_ID" \
-H "Authorization: Bearer $DISSOLVE_API_KEY"import { Dissolve } from '@dissolve-email/sdk';
const client = new Dissolve(); // reads DISSOLVE_API_KEY
const result = await client.v1.getMessage(inboxId, messageId);import os, requests
API_KEY = os.environ["DISSOLVE_API_KEY"]
response = requests.get(f"https://api.dissolve.email/v1/inboxes/{inbox_id}/messages/{message_id}", headers={"Authorization": f"Bearer {API_KEY}"})
print(response.json())Response 200
{
"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"
}
}List a message's attachments
/v1/inboxes/{id}/messages/{messageId}/attachmentsmessages:readName, type and size of each attachment. Listing works on every plan; downloading needs Pro or Business.
Path parameters
| Name | Description |
|---|---|
id | The message id. |
messageId | The message id. |
curl "https://api.dissolve.email/v1/inboxes/$INBOX_ID/messages/$MESSAGE_ID/attachments" \
-H "Authorization: Bearer $DISSOLVE_API_KEY"import { Dissolve } from '@dissolve-email/sdk';
const client = new Dissolve(); // reads DISSOLVE_API_KEY
const result = await client.v1.listAttachments(inboxId, messageId);import os, requests
API_KEY = os.environ["DISSOLVE_API_KEY"]
response = requests.get(f"https://api.dissolve.email/v1/inboxes/{inbox_id}/messages/{message_id}/attachments", headers={"Authorization": f"Bearer {API_KEY}"})
print(response.json())Response 200
[
{
"id": "att1Xc5VbN8mQz2Rk7TpW",
"messageId": "Qm8wZ1kX0pLr7aYtV3nBc",
"filename": "invoice.pdf",
"contentType": "application/pdf",
"size": 48213,
"createdAt": "2026-11-19T10:02:11.000Z"
}
]Download an attachment
/v1/inboxes/{id}/messages/{messageId}/attachments/{attachmentId}messages:readPro and upThe file itself, served as a download (Content-Disposition: attachment, nosniff) whatever its type. Pro and Business.
Path parameters
| Name | Description |
|---|---|
id | The message id. |
messageId | The message id. |
attachmentId | The attachment id. |
curl "https://api.dissolve.email/v1/inboxes/$INBOX_ID/messages/$MESSAGE_ID/attachments/$ATTACHMENT_ID" \
-H "Authorization: Bearer $DISSOLVE_API_KEY"import { Dissolve } from '@dissolve-email/sdk';
const client = new Dissolve(); // reads DISSOLVE_API_KEY
const result = await client.v1.downloadAttachment(inboxId, messageId, attachmentId);import os, requests
API_KEY = os.environ["DISSOLVE_API_KEY"]
response = requests.get(f"https://api.dissolve.email/v1/inboxes/{inbox_id}/messages/{message_id}/attachments/{attachment_id}", headers={"Authorization": f"Bearer {API_KEY}"})
response.raise_for_status()Response 200 (application/octet-stream): the bytes, or an empty body.
Something wrong or missing on this page? Tell us at support@dissolve.email.View as Markdown