---
title: "Give an agent its own phone number and inbox"
description: "Give an AI agent a dedicated phone number and an email inbox on inbox.ai, receive its incoming SMS and mail as events, and reply from the CLI, MCP, or API."
canonical: "https://bird.com/docs/ai/agent-number-and-inbox"
---

# Give an agent its own phone number and inbox

An agent that talks to people needs an address they can reach. This guide gives an agent two: an email inbox on `inbox.ai` and a dedicated phone number. Both belong to your workspace, both receive as well as send, and you can set up both from the [CLI](/docs/ai/cli-for-agents), the [MCP server](/docs/ai/mcp-server), or the API.

## Before you start

- Install the [Bird CLI](/docs/cli) and sign in, or connect the [MCP server](/docs/ai/mcp-server). [Set up your coding agent](/docs/ai/set-up-your-agent) covers both, and [self-serve signup](/docs/ai/self-serve-signup) creates an account from a terminal.
- Fund your organization's wallet. A number has a setup price and a recurring charge, and sends draw on the same balance. A person adds funds in the dashboard: see [Payment methods and wallet](/docs/knowledge-base/billing/payment-methods-wallet).
- Complete identity verification in [**Identity Center**](https://bird.com/dashboard/w/trust) before you buy a number. The first number purchase in an organization requires it, and only an organization owner can complete it.

## Scopes for setup and for the agent

Setup needs more access than the agent needs afterward. `bird auth login` asks for read-only access by default, so name the write scopes when you sign in.

| Task                                    | Scope                      | Who needs it |
| --------------------------------------- | -------------------------- | ------------ |
| Create the mailbox                      | `mailbox_management:write` | Setup        |
| Search for a number and order it        | `numbers:write`            | Setup        |
| Subscribe a webhook endpoint            | `webhooks:write`           | Setup        |
| Enable SMS destination countries        | `sms_management:write`     | Setup        |
| Read the mailbox's threads and reply    | `mailbox:write`            | The agent    |
| Send a text message and read its status | `sms:write`                | The agent    |

This sign-in covers every command in this guide:

```bash
bird auth login --scope mailbox_management:write --scope mailbox:write --scope numbers:write --scope webhooks:write --scope sms_management:write --scope sms:write
```

Once setup is done, the agent needs `mailbox:write` and `sms:write` and nothing else on this list. An agent that subscribes to its own events through [MCP Events](/docs/ai/mcp-events) needs `webhooks:write` as well. [Agent controls](/docs/ai/agent-controls) explains how to give the agent a credential with only those scopes.

## 1. Claim an inbox

Create a mailbox on the shared `inbox.ai` domain. Leave out the local part and Bird generates an available address:

```bash
bird email mailboxes create --name "Support agent" --receive-policy open
```

The response carries the mailbox `id` and its `address`, such as `a7f3k2@inbox.ai`. The address is yours from that moment and the mailbox can receive mail right away. You do not verify a domain or run a mail server.

The `open` receive policy accepts mail unless a receive rule blocks it. To accept less, use `replies_only`, `allowlist`, or `drop`. A specific local part, such as `support@inbox.ai`, is a paid-plan allowance, and a mailbox can also live on one of your own domains. [Agent mailboxes](/docs/guides/email/mailboxes) covers addresses, receive rules, and retention.

MCP clients call `email_mailboxes_create`. Over the API, the call is `POST /v1/email/mailboxes`. [Claim your first agent mailbox](/docs/get-started/agent-mailboxes) walks through the API calls.

## 2. Buy a phone number

Search one country for numbers on sale, then order the one you want. This search returns United States local numbers that carry both SMS and voice:

```bash
bird numbers available list --country-code US --number-type local --capabilities sms --capabilities voice
```

Each result shows the number, its type, and its setup and recurring price for your organization. Two more fields matter before you buy. `ownership_registration_required` means the number needs ownership paperwork after the purchase. `ownership_address_scope` says where your business address must be for that paperwork, and the address is checked only after you buy the number.

Order a number by its E.164 value:

```bash
bird numbers orders create --number +12025550123
```

A person confirms every order placed from the CLI or the MCP server. Both need an OAuth sign-in and a confirmation in the browser:

- **On the CLI**, the command prints a review link and a `confirmation_id` on stderr, then waits. A person opens the link and confirms the order, and the command prints the result. A `BIRD_API_KEY` in the environment takes precedence over the sign-in and the command fails, so unset it first.
- **Over MCP**, `numbers_orders_create` does not return the order on the first call. The server either asks the client to open the review link for the person, or returns a pending result at once with a `review_url` and a `confirmation_id`. With a pending result, show the person the link, and do not order again. After they confirm, repeat the same call with `bird/confirmation-id` set to that ID in the request metadata, or read the result with `operation_confirmations_get`.

The API does not use this confirmation. `POST /v1/numbers/orders` accepts an API key with `numbers:write`, as [Buy and release a number](/docs/guides/numbers/buying-numbers) shows.

Most orders complete in the request. An order that waits on a carrier is still running when the command returns. Read it until its status is `completed` or `failed`:

```bash
bird numbers orders get <order-id>
```

A setup fee already charged is usually not refunded when an order fails, so check the price in the search before you order.

A completed order carries the number's `number_id`. The order can be `completed` before the number can carry traffic, so read the number itself:

```bash
bird numbers get <number-id>
```

The number is ready when its `status` is `active` and, where `ownership` is set, `ownership.blocked_at` is `null`. Two things can keep it from working:

- **Ownership paperwork.** Some countries ask for it. While the number's `status` is `pending_ownership_registration`, it carries no incoming or outgoing voice calls and sends no SMS. [File a number's ownership paperwork](/docs/guides/numbers/ownership-paperwork) shows what to file and how the review works.
- **Sender registration.** A United States local number needs [10DLC registration](/docs/guides/sms/10dlc) before it sends SMS. A United States toll-free number needs toll-free verification instead. [SMS sender IDs](/docs/guides/sms/senders) lists what each country requires.

MCP clients call `numbers_available_list`, `numbers_orders_create`, `numbers_orders_get`, and `numbers_get`.

## 3. Receive incoming messages

Mail that reaches the inbox emits `email_mailbox.message_received`. A text message sent to the number emits `sms.received`. Deliver those events to the agent in one of three ways:

- **A webhook endpoint you run.** Subscribe the endpoint to both events and verify each signature. See [Webhooks & events](/docs/guides/webhooks).
- **A hosted agent.** Bird starts a Claude Managed Agents session or wakes a Grok Bot routine for each incoming message. See [Route messages to your AI agent](/docs/ai/route-messages-to-an-agent).
- **An MCP client.** A client that supports MCP Events subscribes to either event on the hosted MCP server and receives it as a signed webhook. See [MCP Events](/docs/ai/mcp-events).

Before the agent acts on a received email, check `dkim_pass` and `spf_pass` on the event, as [Using authentication results](/docs/guides/email/receiving-email#using-authentication-results) describes. `authentication` and `dmarc_pass` are not populated yet, and `from` on this event is the envelope sender, which can differ from the sender the recipient sees. Delivery to the inbox does not prove who sent the message.

## 4. Reply as the agent

Reply to an email in its thread. A reply names the thread and the message it answers. An agent started by `email_mailbox.message_received` has both on the event, as `thread_id` and `message_id`. From a terminal, list the mailbox's threads, then the messages in one, then reply:

```bash
bird email threads list --mailbox-id <mailbox-id>
bird email threads messages list <thread-id>
bird email threads messages reply <thread-id> <message-id> --text "Thanks, we received your request."
```

The reply goes out from the mailbox's own address and folds into the same conversation. MCP clients call `email_threads_messages_reply`.

Send a text message from the agent's number. Enable the recipient's country as an SMS destination first, and finish any sender registration the destination requires:

```bash
bird sms send --from +12025550123 --to +12025550145 --text "Your booking is confirmed." --category transactional
```

The response is `202` with the message `id`, and its `status` is `accepted`. Read the message again with `bird sms get` and that `id` to see whether it was delivered. MCP clients call `sms_send` and `sms_get`.

## Mobile data for a device

If the agent runs on a phone or another device that needs its own connection, a [Bird eSIM](/docs/guides/esim/overview) gives that device mobile data. An eSIM is a data package for a compatible device. It does not give the agent a phone number for calls or SMS: use the number from step 2 for those.

## Next steps

- [Agent controls](/docs/ai/agent-controls): scope the agent's key, allow its destination countries, and set a daily spend limit.
- [Agent mailboxes](/docs/guides/email/mailboxes): addresses, receive rules, events, and retention.
- [Numbers overview](/docs/guides/numbers/overview): number types, capabilities, and statuses.
- [Route messages to your AI agent](/docs/ai/route-messages-to-an-agent): connect incoming messages to Claude or Grok Bot.

## Related resources

- [Setting up your coding agent](/learn/basics/setting-up-your-coding-agent) (video)
- [What is an MCP server, and how does an agent use one to send messages?](/explained/platform/what-is-an-mcp-server-and-how-does-an-agent-send-messages) (answer)
- [Coding agents](/ai) (product)
- [Build with AI agents](/learn/paths/agents) (course)

[Get an implementation brief](/learn/workspace?topic=agents)
