> ## Documentation Index
> Fetch the complete documentation index at: https://nuntly.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Messages

> List, retrieve, and inspect received messages. Access message content, headers, and attachments through the API.

Messages represent individual emails received on your domain. Each message belongs to a thread and contains sender information, recipients, subject, and a reference to its content (plain text, HTML, and raw MIME).

## List messages

Retrieve a paginated list of received messages across all your inboxes. You can filter by domain or sender address.

```typescript theme={null}
import { Nuntly } from '@nuntly/sdk';

const nuntly = new Nuntly({
  apiKey: process.env.NUNTLY_API_KEY,
});

// List all messages
const messages = await nuntly.messages.list();

// Filter by domain
const domainMessages = await nuntly.messages.list({
  domainId: 'your-domain-id',
});

// Filter by sender
const fromMessages = await nuntly.messages.list({
  from: 'sender@example.com',
});
```

### Available filters

| Parameter  | Description                                             |
| ---------- | ------------------------------------------------------- |
| `domainId` | Filter messages by a specific domain.                   |
| `from`     | Filter messages by sender address.                      |
| `cursor`   | Cursor for pagination.                                  |
| `limit`    | Maximum number of results to return (1-30, default 30). |

## Retrieve a message

Get the full details of a single message by its ID. The response includes inbox information showing which inbox the message was routed to.

```typescript theme={null}
const message = await nuntly.messages.retrieve('imsg_01kabn43yqyxn2bx4ve84mczd3');

console.log('From:', message.data.from);
console.log('Subject:', message.data.subject);
console.log('Attachments:', message.data.attachmentCount);
```

### Message fields

| Field             | Description                                                                               |
| ----------------- | ----------------------------------------------------------------------------------------- |
| `id`              | The unique message identifier.                                                            |
| `inboxId`         | The inbox the message was routed to, or `null` for the default catch-all.                 |
| `threadId`        | The thread this message belongs to.                                                       |
| `messageId`       | The email Message-ID header.                                                              |
| `from`            | The sender in RFC 5322 format (e.g. `Jane Doe <jane@example.com>` or `jane@example.com`). |
| `to`              | The recipient addresses.                                                                  |
| `cc`              | The CC addresses.                                                                         |
| `bcc`             | The BCC addresses.                                                                        |
| `replyTo`         | The Reply-To addresses.                                                                   |
| `subject`         | The message subject line.                                                                 |
| `receivedAt`      | The timestamp when the message was received.                                              |
| `status`          | The message status (`received`, `sent`, `discarded`, or `failed`).                        |
| `attachmentCount` | The number of attachments.                                                                |
| `headers`         | The raw email headers as a key-value map. Included on single retrieval only.              |

## Get message content

Retrieve presigned download URLs for the message body in different formats. Each content item includes the download URL, the uncompressed size in bytes, and when the URL expires.

By default, only the HTML format is returned. Use the `format` parameter to request additional formats.

```typescript theme={null}
// HTML only (default)
const content = await nuntly.messages.getContent('imsg_01kabn43yqyxn2bx4ve84mczd3');

if (content.data.html) {
  console.log('HTML URL:', content.data.html.downloadUrl);
  console.log('HTML size:', content.data.html.size, 'bytes');
  console.log('Expires at:', content.data.html.expiresAt);
}

// Request specific formats
const full = await nuntly.messages.getContent('imsg_01kabn43yqyxn2bx4ve84mczd3', {
  format: ['html', 'text'],
});
```

Use the `format` query parameter to control which formats are included in the response. Requesting only the formats you need avoids unnecessary downloads.

| Parameter | Description                                                                          |
| --------- | ------------------------------------------------------------------------------------ |
| `format`  | Formats to retrieve: `html`, `text`, or `mime`. Defaults to `html` only. Repeatable. |

Each of `text`, `html`, and `mime` is either a content item object or `null` if not requested or not available for the message.

| Field  | Description                                                              |
| ------ | ------------------------------------------------------------------------ |
| `text` | Plain text content, or `null`.                                           |
| `html` | HTML content, or `null`.                                                 |
| `mime` | Raw MIME (.eml) content, or `null`. Returned for received messages only. |

Each content item has the following fields:

| Field         | Description                            |
| ------------- | -------------------------------------- |
| `downloadUrl` | Presigned download URL.                |
| `size`        | Uncompressed size in bytes, or `null`. |
| `expiresAt`   | When the URL expires.                  |

## Attachments

### List attachments

Retrieve all attachments for a specific message.

```typescript theme={null}
const attachments = await nuntly.messages.listAttachments('imsg_01kabn43yqyxn2bx4ve84mczd3');

for (const attachment of attachments.data) {
  console.log(`${attachment.filename} (${attachment.contentType}, ${attachment.size} bytes)`);
}
```

### Retrieve an attachment

Get a single attachment with a presigned download URL.

```typescript theme={null}
const attachment = await nuntly.messages.getAttachment(
  'imsg_01kabn43yqyxn2bx4ve84mczd3',
  'iatt_01kabn43yqyxn2bx4ve84mczd3',
);

console.log('Download URL:', attachment.data.downloadUrl);
console.log('Content type:', attachment.data.contentType);
console.log('Size:', attachment.data.size);
```

### Attachment fields

| Field                | Description                                             |
| -------------------- | ------------------------------------------------------- |
| `id`                 | The unique attachment identifier.                       |
| `filename`           | The original filename, or `null`.                       |
| `contentType`        | The MIME content type (for example, `application/pdf`). |
| `size`               | The size in bytes.                                      |
| `contentDisposition` | Either `inline` or `attachment`.                        |
| `contentId`          | The CID for inline images, or `null`.                   |
| `downloadUrl`        | Presigned download URL (included on single retrieval).  |

## Next steps

<CardGroup cols={2}>
  <Card title="Inboxes" icon="mailbox" href="/docs/guides/receiving-inboxes">
    Create and manage inboxes to route incoming emails
  </Card>

  <Card title="Threads" icon="messages" href="/docs/guides/receiving-threads">
    Understand how messages are grouped into conversations
  </Card>

  <Card title="Send, reply, and forward" icon="reply" href="/docs/guides/receiving-send-reply">
    Respond to received messages from your inboxes
  </Card>
</CardGroup>