How do I create my first inbox?

Get up and running with your first AgentMail inbox.

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

Install the SDK

TypeScript

$ npm install agentmail

Create an inbox

TypeScript

1 import { AgentMailClient } from "agentmail";
2 
3 const client = new AgentMailClient({ apiKey: "am_..." });
4 
5 // Create an inbox with a random address on agentmail.to
6 const inbox = await client.inboxes.create();
7 console.log(`Inbox created: ${inbox.inboxId}`);

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

Customize your inbox

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

TypeScript

1 const inbox = await client.inboxes.create({
2   username: "support",
3   domain: "yourcompany.com",
4   displayName: "Support Agent",
5 });
6 
7 // inbox.inboxId will be support@yourcompany.com
8 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, AgentMail uses the default @agentmail.to 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, AgentMail returns the existing inbox instead of creating a new one:

TypeScript

1 const inbox = await client.inboxes.create({
2   username: "my-agent",
3   clientId: "my-agent-inbox-v1",
4   displayName: "My Agent",
5 });
6 
7 // 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

1 await client.inboxes.messages.send(inbox.inboxId, {
2   to: "recipient@example.com",
3   subject: "Hello from my agent!",
4   text: "This is a plain text version.",
5   html: "<p>This is an <strong>HTML</strong> version.</p>",
6 });

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

List your inboxes

TypeScript

1 const inboxes = await client.inboxes.list();
2 console.log(`You have ${inboxes.count} inboxes.`);
3 
4 for (const inbox of inboxes.inboxes) {
5   console.log(`  ${inbox.inboxId}`);
6 }

Next steps

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

Send and receive emails in a conversational loop
Set up webhooks to get notified when emails arrive
Use labels to track message state in your agent workflows

1	import { AgentMailClient } from "agentmail";
2
3	const client = new AgentMailClient({ apiKey: "am_..." });
4
5	// Create an inbox with a random address on agentmail.to
6	const inbox = await client.inboxes.create();
7	console.log(`Inbox created: ${inbox.inboxId}`);

1	const inbox = await client.inboxes.create({
2	username: "support",
3	domain: "yourcompany.com",
4	displayName: "Support Agent",
5	});
6
7	// inbox.inboxId will be support@yourcompany.com
8	console.log(`Inbox created: ${inbox.inboxId}`);

1	const inbox = await client.inboxes.create({
2	username: "my-agent",
3	clientId: "my-agent-inbox-v1",
4	displayName: "My Agent",
5	});
6
7	// Safe to call multiple times: same inbox returned every time

1	await client.inboxes.messages.send(inbox.inboxId, {
2	to: "recipient@example.com",
3	subject: "Hello from my agent!",
4	text: "This is a plain text version.",
5	html: "<p>This is an <strong>HTML</strong> version.</p>",
6	});

1	const inboxes = await client.inboxes.list();
2	console.log(`You have ${inboxes.count} inboxes.`);
3
4	for (const inbox of inboxes.inboxes) {
5	console.log(` ${inbox.inboxId}`);
6	}