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

# Inboxes

> Create and manage inboxes to route incoming emails.

Inboxes define how incoming emails are routed on your domain. Each inbox maps a local address (the part before the `@`) to a routing target. For example, an inbox with address `support` on the domain `yourdomain.com` receives all emails sent to `support@yourdomain.com`.

## Default catch-all inbox

When you enable receiving on a domain, Nuntly automatically creates a default catch-all inbox with the address `*`. This inbox receives any email that does not match a specific inbox address. You do not need to create it manually.

## Routing logic

When an email arrives, Nuntly matches the recipient address against your inboxes in this order:

1. **Exact match.** If an inbox address matches the local part of the recipient (for example, `support` matches `support@yourdomain.com`), the message is routed to that inbox.
2. **Default catch-all.** If no exact match is found, the message is routed to the default `*` inbox.

<Note>The default catch-all inbox does not count toward your plan limit.</Note>

## Create an inbox

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

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

const inbox = await nuntly.inboxes.create({
  domainId: 'your-domain-id',
  address: 'support',
  name: 'Customer Support',
});

console.log('Inbox ID:', inbox.data.id);
console.log('Full address:', `${inbox.data.address}@${inbox.data.domainName}`);
```

### Create request fields

| Field         | Required | Description                                                                  |
| ------------- | -------- | ---------------------------------------------------------------------------- |
| `domainId`    | Yes      | The ID of the domain for this inbox.                                         |
| `address`     | Yes      | The local part of the email address (before the `@`). Maximum 64 characters. |
| `name`        | No       | A display name for the inbox. Maximum 255 characters.                        |
| `namespaceId` | No       | The ID of a namespace to assign the inbox to.                                |
| `agentId`     | No       | An external AI agent identifier. Maximum 255 characters.                     |

## List inboxes

```typescript theme={null}
// List all inboxes
const inboxes = await nuntly.inboxes.list();

// Filter by namespace
const namespaceInboxes = await nuntly.inboxes.list({
  namespaceId: 'ns_01kabn43yqyxn2bx4ve84mczd3',
});

// Filter by status
const activeInboxes = await nuntly.inboxes.list({
  status: 'active',
});
```

## Retrieve an inbox

Retrieve a single inbox with thread statistics.

```typescript theme={null}
const inbox = await nuntly.inboxes.retrieve('ibx_01kabn43yqyxn2bx4ve84mczd3');

console.log('Address:', inbox.data.address);
console.log('Total threads:', inbox.data.totalThreads);
console.log('Unread threads:', inbox.data.unreadThreads);
```

## Update an inbox

```typescript theme={null}
await nuntly.inboxes.update('ibx_01kabn43yqyxn2bx4ve84mczd3', {
  name: 'Updated Support Inbox',
  namespaceId: 'ns_01kabn43yqyxn2bx4ve84mczd3',
  agentId: 'my-support-agent',
  status: 'active',
});
```

### Update request fields

| Field         | Description                                                 |
| ------------- | ----------------------------------------------------------- |
| `name`        | The display name. Set to `null` to clear.                   |
| `namespaceId` | The namespace ID. Set to `null` to remove from a namespace. |
| `agentId`     | The AI agent identifier. Set to `null` to remove the agent. |
| `status`      | Set to `active` or `disabled`.                              |

## Delete an inbox

Deleting an inbox is a soft delete. The inbox is marked as deleted and no longer receives messages.

```typescript theme={null}
await nuntly.inboxes.delete('ibx_01kabn43yqyxn2bx4ve84mczd3');
```

<Warning>
  Deleting an inbox stops routing messages to that address. Any future emails sent to the deleted address will fall through to the default catch-all
  inbox.
</Warning>

## List threads in an inbox

You can list threads directly from an inbox. See [threads](/docs/guides/receiving-threads) for more details on working with threads.

```typescript theme={null}
const threads = await nuntly.inboxes.listThreads('ibx_01kabn43yqyxn2bx4ve84mczd3', {
  isRead: false,
});

for (const thread of threads.data) {
  console.log(`${thread.subject} (${thread.messageCount} messages)`);
}
```

## Next steps

<CardGroup cols={2}>
  <Card title="Namespaces" icon="folder-tree" href="/docs/guides/receiving-namespaces">
    Organize inboxes into groups for multi-tenant applications
  </Card>

  <Card title="AI agent inboxes" icon="bot" href="/docs/guides/receiving-agents">
    Assign AI agents to inboxes for automated processing
  </Card>
</CardGroup>