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

# Namespaces

> Organize inboxes into namespaces for isolation and multi-tenant grouping. Understand when to use namespaces, common patterns, and how to map your internal IDs.

A namespace is a named container for inboxes. It lets you group and isolate inboxes by any boundary that makes sense for your application: a customer account, a customer organization, a project, a team, a workspace or an AI agent.

Without namespaces, all inboxes share the same flat list. For simple setups, a few inboxes for one team, that is fine. Once you have multiple customers, tenants, or agents each needing their own inboxes, namespaces become the organizing layer that keeps everything separated and queryable.

## When to use namespaces

Use namespaces when you need to:

* **Isolate inboxes by tenant.** Each customer or account gets their own namespace, so queries are naturally scoped and there is no risk of data leaking between tenants.
* **Group inboxes by team or function.** A sales namespace, a support namespace, an operations namespace, each with its own set of addresses.
* **Manage AI agent inboxes independently.** An agent with multiple inboxes (for example, one per customer it serves) benefits from a dedicated namespace to track and query its memory.

You do not need namespaces for a single-team setup with a small number of inboxes.

## The `externalId` field

Every namespace has an optional `externalId` field. Use it to store your own internal identifier, a tenant ID, an account UUID, a customer slug, directly on the namespace.

This eliminates the need for a separate mapping table. When a webhook event arrives or when you need to scope a query to a specific tenant, look up the namespace by `externalId` and filter from there.

## Common patterns

### Per-customer inboxes in a SaaS product

Each account in your product gets a namespace. Within that namespace, you create whatever inboxes that account needs: `support@`, `billing@`, `notifications@`. When a customer is deleted or suspended, you can disable the entire namespace in one call.

Because namespaces carry your `externalId`, a single API call is all it takes to go from "I have a tenant ID" to "here are all the inboxes and messages for that tenant".

### Per-client inboxes in an agency

An agency managing email for multiple clients creates one namespace per client. Each namespace gets a set of inboxes matched to that client's domain and workflow. The agency's internal system maps client IDs to namespace IDs via `externalId` and scopes all queries accordingly.

### AI agent namespaces

An AI agent platform can give each agent, or each agent instance, its own namespace. The agent's inboxes live inside that namespace, keeping its activity isolated from other agents. The agent memory API can then be queried scoped to specific inboxes and threads within the namespace.

## Create a namespace

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

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

const namespace = await nuntly.namespaces.create({
  name: 'Acme Corp',
  externalId: 'tenant_12345',
});

console.log('Namespace ID:', namespace.data.id);
```

### Create request fields

| Field        | Required | Description                                                                          |
| ------------ | -------- | ------------------------------------------------------------------------------------ |
| `name`       | Yes      | The display name of the namespace. Maximum 255 characters.                           |
| `externalId` | No       | An external identifier for mapping to your internal systems. Maximum 255 characters. |

## List namespaces

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

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

## Retrieve a namespace

Retrieve a single namespace with inbox statistics.

```typescript theme={null}
const namespace = await nuntly.namespaces.retrieve('ns_01kabn43yqyxn2bx4ve84mczd3');

console.log('Name:', namespace.data.name);
console.log('External ID:', namespace.data.externalId);
console.log('Inbox count:', namespace.data.inboxCount);
console.log('Active inbox count:', namespace.data.activeInboxCount);
```

## Update a namespace

```typescript theme={null}
await nuntly.namespaces.update('ns_01kabn43yqyxn2bx4ve84mczd3', {
  name: 'Acme Corp (Updated)',
  externalId: 'tenant_67890',
  status: 'active',
});
```

### Update request fields

| Field        | Description                                      |
| ------------ | ------------------------------------------------ |
| `name`       | The display name. Maximum 255 characters.        |
| `externalId` | The external identifier. Set to `null` to clear. |
| `status`     | Set to `active` or `disabled`.                   |

## Delete a namespace

Deleting a namespace is a soft delete. You cannot delete a namespace that still has active inboxes. Move or delete the inboxes first.

```typescript theme={null}
await nuntly.namespaces.delete('ns_01kabn43yqyxn2bx4ve84mczd3');
```

<Warning>Deleting a namespace with active inboxes will fail. Remove or reassign all inboxes in the namespace before deleting it.</Warning>

## List inboxes in a namespace

Retrieve the inboxes that belong to a specific namespace.

```typescript theme={null}
const inboxes = await nuntly.namespaces.listInboxes('ns_01kabn43yqyxn2bx4ve84mczd3');

for (const inbox of inboxes.data) {
  console.log(`${inbox.address}@${inbox.domainName}`);
}
```

## Multi-tenant provisioning example

A common pattern is to create a namespace when a new tenant signs up, using `externalId` to map between your tenant IDs and Nuntly namespaces.

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

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

// When a new tenant signs up, provision their namespace and inboxes
async function provisionTenant(tenant: { id: string; companyName: string }) {
  const namespace = await nuntly.namespaces.create({
    name: tenant.companyName,
    externalId: tenant.id,
  });

  // Create standard inboxes for this tenant
  await Promise.all([
    nuntly.inboxes.create({
      domainId: process.env.DOMAIN_ID,
      address: `support-${tenant.id}`,
      name: `${tenant.companyName} Support`,
      namespaceId: namespace.data.id,
    }),
    nuntly.inboxes.create({
      domainId: process.env.DOMAIN_ID,
      address: `billing-${tenant.id}`,
      name: `${tenant.companyName} Billing`,
      namespaceId: namespace.data.id,
    }),
  ]);

  return namespace.data.id;
}

// Later, look up inboxes for a tenant using only your internal ID
async function getInboxesForTenant(tenantId: string) {
  const namespaces = await nuntly.namespaces.list();
  const namespace = namespaces.data.find((ns) => ns.externalId === tenantId);
  if (!namespace) return [];
  return nuntly.namespaces.listInboxes(namespace.id);
}
```

## Next steps

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

  <Card title="AI agent inboxes" icon="bot" href="/docs/guides/receiving-agents">
    Manage agent inboxes with namespaces
  </Card>
</CardGroup>