# Messages API

> Mail in an inbox and its attachments. Every messages endpoint with its scope, parameters, body and an example answer.

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

Base URL `https://api.dissolve.email`. Send an API key or OAuth access token as `Authorization: Bearer <token>` ([Authentication](/authentication)); an OAuth token needs the scope on each endpoint. Errors follow [one shape](/errors).

| Endpoint | Summary |
|---|---|
| `GET /v1/inboxes/{id}/messages` | [List messages](#list-messages) |
| `GET /v1/inboxes/{id}/messages/{messageId}` | [Get a message](#get-a-message) |
| `GET /v1/inboxes/{id}/messages/{messageId}/attachments` | [List a message's attachments](#list-a-message-s-attachments) |
| `GET /v1/inboxes/{id}/messages/{messageId}/attachments/{attachmentId}` | [Download an attachment](#download-an-attachment) |

### List messages

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

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

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

```ts TypeScript
import { Dissolve } from '@dissolve-email/sdk';

const client = new Dissolve(); // reads DISSOLVE_API_KEY
const result = await client.v1.listMessages(inboxId);
```

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

```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}` (scope `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**

| Name | Description |
|---|---|
| `id` | The message id. |
| `messageId` | The message id. |

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

```ts TypeScript
import { Dissolve } from '@dissolve-email/sdk';

const client = new Dissolve(); // reads DISSOLVE_API_KEY
const result = await client.v1.getMessage(inboxId, messageId);
```

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

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

Name, 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. |

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

```ts TypeScript
import { Dissolve } from '@dissolve-email/sdk';

const client = new Dissolve(); // reads DISSOLVE_API_KEY
const result = await client.v1.listAttachments(inboxId, messageId);
```

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

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

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

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

```ts TypeScript
import { Dissolve } from '@dissolve-email/sdk';

const client = new Dissolve(); // reads DISSOLVE_API_KEY
const result = await client.v1.downloadAttachment(inboxId, messageId, attachmentId);
```

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