> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://docs.postnuvia.com/llms.txt.

# How do I create my first inbox?

Creating an inbox gives your AI agent its own email address. You can create inboxes on the default `@postnuvia.com` domain or on your own custom domain.

## Install the SDK

**`TypeScript`**

```bash title="TypeScript"
npm install postnuvia
```

## Create an inbox

**`TypeScript`**

```typescript title="TypeScript"
import { PostNuviaClient } from "postnuvia";

const client = new PostNuviaClient({ apiKey: "am_..." });

// Create an inbox with a random address on postnuvia.com
const inbox = await client.inboxes.create();
console.log(`Inbox created: ${inbox.inboxId}`);
```

The inbox now has a unique email address (e.g., `randomname@postnuvia.com`) and can send and receive emails immediately.

## Customize your inbox

You can specify a username, domain, and display name:

**`TypeScript`**

```typescript title="TypeScript"
const inbox = await client.inboxes.create({
  username: "support",
  domain: "yourcompany.com",
  displayName: "Support Agent",
});

// inbox.inboxId will be support@yourcompany.com
console.log(`Inbox created: ${inbox.inboxId}`);
```

> **Note**
>
> Using a custom domain requires a verified domain. See the [Creating Custom Domains](/custom-domains) guide to set one up. If you don't specify a domain, PostNuvia uses the default `@postnuvia.com` domain.

## Use client\_id for idempotency

If your agent creates inboxes programmatically (e.g., on startup), use `clientId` to prevent duplicates. If an inbox with the same `clientId` already exists, PostNuvia returns the existing inbox instead of creating a new one:

**`TypeScript`**

```typescript title="TypeScript"
const inbox = await client.inboxes.create({
  username: "my-agent",
  clientId: "my-agent-inbox-v1",
  displayName: "My Agent",
});

// Safe to call multiple times: same inbox returned every time
```

## Send your first email

Once the inbox is created, you can send an email:

**`TypeScript`**

```typescript title="TypeScript"
await client.inboxes.messages.send(inbox.inboxId, {
  to: "recipient@example.com",
  subject: "Hello from my agent!",
  text: "This is a plain text version.",
  html: "<p>This is an <strong>HTML</strong> version.</p>",
});
```

> **Note**
>
> Always provide both `text` and `html` when sending emails. This ensures readability across all email clients and improves deliverability.

## List your inboxes

**`TypeScript`**

```typescript title="TypeScript"
const inboxes = await client.inboxes.list();
console.log(`You have ${inboxes.count} inboxes.`);

for (const inbox of inboxes.inboxes) {
  console.log(`  ${inbox.inboxId}`);
}
```

## Next steps

Now that you have an inbox, explore what you can do with it:

* [Send and receive emails](/sending-receiving-email) in a conversational loop
* [Set up webhooks](/webhook-setup) to get notified when emails arrive
* [Use labels](/labels) to track message state in your agent workflows