Skip to main content
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.
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

FieldRequiredDescription
domainIdYesThe ID of the domain for this inbox.
addressYesThe local part of the email address (before the @). Maximum 64 characters.
nameNoA display name for the inbox. Maximum 255 characters.
namespaceIdNoThe ID of a namespace to assign the inbox to.
agentIdNoAn 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

FieldDescription
nameThe display name. Set to null to clear.
namespaceIdThe namespace ID. Set to null to remove from a namespace.
agentIdThe AI agent identifier. Set to null to remove the agent.
statusSet 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)`);
}

​
Next steps

Namespaces

Organize inboxes into groups for multi-tenant applications

AI agent inboxes

Assign AI agents to inboxes for automated processing