---
title: "Claim your first agent mailbox"
description: "Create a mailbox on inbox.ai, receive mail into a thread, and reply through the API to complete an agent's two-way email loop."
canonical: "https://bird.com/docs/get-started/agent-mailboxes"
---

# Claim your first agent mailbox

This guide completes a two-way conversation: claim an inbox on `inbox.ai`, receive a message into a thread, read it, and reply. You do not need to verify a domain or run a mail server.

## 1. Create an API key

In the dashboard, go to [**Developers** > **API keys**](https://bird.com/dashboard/w/api-keys) and create a key. Under the **Email** group, enable the `mailbox` and `mailbox_management` scopes. Keys look like `bk_us1_...` or `bk_eu1_...`; the region in the prefix selects the API host.

```bash
export BIRD_API_KEY="bk_us1_..."
```

## 2. Claim a mailbox

Create a mailbox on the shared `inbox.ai` domain. Omit the local part and Bird generates an available address. The `open` receive policy accepts mail unless a receive rule blocks it.

**TypeScript**

```typescript
const mailbox = await bird.email.mailboxes.create({ display_name: "Support" });
console.log(mailbox.address); // "abc123@inbox.ai"
```

Examples: [TypeScript](/docs/get-started/agent-mailboxes.ts.md) · [Python](/docs/get-started/agent-mailboxes.py.md) · [Go](/docs/get-started/agent-mailboxes.go.md) · [PHP](/docs/get-started/agent-mailboxes.php.md) · [CLI](/docs/get-started/agent-mailboxes.cli.md) · [MCP](/docs/get-started/agent-mailboxes.mcp.md) · [cURL](/docs/get-started/agent-mailboxes.curl.md)

The response carries the mailbox `id` and the `address` claimed for you. Send an email to that address from any mail client to give the next step something to read.

## 3. Read the thread

Inbound mail becomes a thread on the mailbox. List threads, then read the messages in the first one.

![A mailbox thread in the Bird dashboard showing an inbound message and a reply in the two-way conversation loop](/images/docs/dashboard-mailboxes.png)

**TypeScript**

```typescript
for await (const thread of bird.email.threads.list({ mailbox_id: "mbx_01abc" })) {
  console.log(thread.id, thread.subject);
}
```

Examples: [TypeScript](/docs/get-started/agent-mailboxes.ts.md) · [Python](/docs/get-started/agent-mailboxes.py.md) · [Go](/docs/get-started/agent-mailboxes.go.md) · [PHP](/docs/get-started/agent-mailboxes.php.md) · [CLI](/docs/get-started/agent-mailboxes.cli.md) · [MCP](/docs/get-started/agent-mailboxes.mcp.md) · [cURL](/docs/get-started/agent-mailboxes.curl.md)

Then read that thread's messages:

**TypeScript**

```typescript
for await (const msg of bird.email.threads.messages.list("thr_01abc")) {
  console.log(msg.id, msg.direction);
}
```

Examples: [TypeScript](/docs/get-started/agent-mailboxes.ts.md) · [Python](/docs/get-started/agent-mailboxes.py.md) · [Go](/docs/get-started/agent-mailboxes.go.md) · [PHP](/docs/get-started/agent-mailboxes.php.md) · [CLI](/docs/get-started/agent-mailboxes.cli.md) · [MCP](/docs/get-started/agent-mailboxes.mcp.md) · [cURL](/docs/get-started/agent-mailboxes.curl.md)

Each message carries its direction (`inbound`) and its `id` (a received message is prefixed `rem_`). Add `include=extracted_text` to inline the quote-stripped body: the new content, without the quoted history an agent would otherwise have to strip itself.

To avoid polling, subscribe to the `email_mailbox.message_received` webhook. It fires when an inbound message reaches the inbox. See the [events](/docs/guides/email/events) reference.

## 4. Reply

Reply to the received message. Use its `rem_` ID from step 3. The reply stays in the same thread and sends from your mailbox's address:

**TypeScript**

```typescript
const reply = await bird.email.threads.messages.reply("thr_01abc", "rem_01xyz", {
  text: "Thanks for reaching out!",
});
console.log(reply.id);
```

Examples: [TypeScript](/docs/get-started/agent-mailboxes.ts.md) · [Python](/docs/get-started/agent-mailboxes.py.md) · [Go](/docs/get-started/agent-mailboxes.go.md) · [PHP](/docs/get-started/agent-mailboxes.php.md) · [CLI](/docs/get-started/agent-mailboxes.cli.md) · [MCP](/docs/get-started/agent-mailboxes.mcp.md) · [cURL](/docs/get-started/agent-mailboxes.curl.md)

You can now claim, receive, read, and reply. To start a conversation instead of answering one, compose a new message on the mailbox (`POST /v1/email/mailboxes/{id}/messages`), which opens a new thread.

## Next steps

- [Agent mailboxes](/docs/guides/email/mailboxes): how threads, receive rules, sending, and retention work.
- [MCP server](/docs/ai/mcp-server): run the same loop from an AI agent through the MCP server.
- [CLI](/docs/cli): `bird email mailboxes` and `bird email threads` for the terminal.
- [SDK quickstarts](/docs/get-started/quickstarts/typescript/email): Go, Python, and TypeScript SDK walkthroughs.

## Related resources

- [Mailbox API](/mailbox-api) (product)

[Get an implementation brief](/learn/workspace?topic=agent-mailboxes)