# 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.

Source: https://docs.dissolve.email/messages

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}/messages` (scope `messages: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](/labels), by id |

```bash cURL
curl "https://api.dissolve.email/v1/inboxes/$INBOX_ID/messages?limit=20" \
  -H "Authorization: Bearer $DISSOLVE_API_KEY"
```

```ts TypeScript
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);
```

```python Python
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()
```

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

> [!WARNING] Do not poll this list
> Listing messages is held to five calls a minute per credential; a sixth answers `429`. To wait for new mail, use [wait](/verification), which holds one request open until mail arrives, or a [webhook](/webhooks).

## Read a message

`GET /v1/inboxes/{id}/messages/{messageId}` (scope `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`.

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

```ts TypeScript
const message = await client.v1.getMessage(inboxId, messageId);
console.log(message.bodyText);
```

```python Python
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}/attachments` (scope `messages: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}` (scope `messages:read`)

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](/rate-limits)).

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

```ts TypeScript
const response = await client.v1.downloadAttachment(inboxId, messageId, attachmentId);
const bytes = new Uint8Array(await response.arrayBuffer());
```

```python Python
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

`GET /api/inbox/{id}/stream` (API key or signed-in 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.

```bash 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](/verification) or a [webhook](/webhooks) is simpler than holding a stream.

> [!NOTE] Scopes
> Reading messages and attachments needs `messages:read`. The stream is not part of `/v1`, so it takes an API key, not an OAuth token.
