Skip to navigation
Getting Started

How do I create my first inbox?

Get up and running with your first PostNuvia 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
npm install postnuvia

Create an inbox

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

Using a custom domain requires a verified domain. See the Creating 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
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
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>",
});

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

List your inboxes

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: