Inboxes

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:

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.
Default catch-all. If no exact match is found, the message is routed to the default * inbox.

The default catch-all inbox does not count toward your plan limit.

Create an inbox

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

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

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

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.

await nuntly.inboxes.delete('ibx_01kabn43yqyxn2bx4ve84mczd3');

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.

List threads in an inbox

You can list threads directly from an inbox. See threads for more details on working with threads.

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

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

Getting started

Sending

Receiving

Configuration

Observability

Webhooks

Best practices

Libraries & tools

Default catch-all inbox

Routing logic

Create an inbox

Create request fields

List inboxes

Retrieve an inbox

Update an inbox

Update request fields

Delete an inbox

List threads in an inbox

Next steps

Namespaces

AI agent inboxes

​Default catch-all inbox

​Routing logic

​Create an inbox

​Create request fields

​List inboxes

​Retrieve an inbox

​Update an inbox

​Update request fields

​Delete an inbox

​List threads in an inbox

​Next steps

Namespaces

AI agent inboxes

Default catch-all inbox

Routing logic

Create an inbox

Create request fields

List inboxes

Retrieve an inbox

Update an inbox

Update request fields

Delete an inbox

List threads in an inbox

Next steps