Skip to content
docs
Browse the docsMessages

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.

EndpointSummary
GET /v1/inboxes/{id}/messagesList messages
GET /v1/inboxes/{id}/messages/{messageId}Get a message
GET /v1/inboxes/{id}/messages/{messageId}/attachmentsList a message's attachments
GET /v1/inboxes/{id}/messages/{messageId}/attachments/{attachmentId}Download an attachment

List messages

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

Messages 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

NameDescription
idThe message id.

Query parameters

NameTypeRequiredDescription
limitintegernoHow many messages to return. Default 200. 1 to 500.
qstringnoWords to find in the subject, sender or text body (Pro and Business). At most 100 characters.
labelstringnoOnly messages carrying this label id.
curl "https://api.dissolve.email/v1/inboxes/$INBOX_ID/messages" \
  -H "Authorization: Bearer $DISSOLVE_API_KEY"

Response 200

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"
    }
  }
]

Get a message

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

One 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

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

Response 200

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"
  }
}

List a message's attachments

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

Name, type and size of each attachment. Listing works on every plan; downloading needs Pro or Business.

Path parameters

NameDescription
idThe message id.
messageIdThe message id.
curl "https://api.dissolve.email/v1/inboxes/$INBOX_ID/messages/$MESSAGE_ID/attachments" \
  -H "Authorization: Bearer $DISSOLVE_API_KEY"

Response 200

JSON
[
  {
    "id": "att1Xc5VbN8mQz2Rk7TpW",
    "messageId": "Qm8wZ1kX0pLr7aYtV3nBc",
    "filename": "invoice.pdf",
    "contentType": "application/pdf",
    "size": 48213,
    "createdAt": "2026-11-19T10:02:11.000Z"
  }
]

Download an attachment

GET/v1/inboxes/{id}/messages/{messageId}/attachments/{attachmentId}messages:readPro and up

The file itself, served as a download (Content-Disposition: attachment, nosniff) whatever its type. Pro and Business.

Path parameters

NameDescription
idThe message id.
messageIdThe message id.
attachmentIdThe attachment id.
curl "https://api.dissolve.email/v1/inboxes/$INBOX_ID/messages/$MESSAGE_ID/attachments/$ATTACHMENT_ID" \
  -H "Authorization: Bearer $DISSOLVE_API_KEY"

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