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)`);
}
Next steps
