Sign inGet Started

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, the MCP server, or the API.

Before you start

  • Install the Bird CLI and sign in, or connect the MCP server. Set up your coding agent covers both, and 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.
  • Complete identity verification in Identity Center 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.

TaskScopeWho needs it
Create the mailboxmailbox_management:writeSetup
Search for a number and order itnumbers:writeSetup
Subscribe a webhook endpointwebhooks:writeSetup
Enable SMS destination countriessms_management:writeSetup
Read the mailbox's threads and replymailbox:writeThe agent
Send a text message and read its statussms:writeThe agent

This sign-in covers every command in this guide:

Przykład kodu
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 needs webhooks:write as well. 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:

Przykład kodu
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 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 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:

Przykład kodu
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:

Przykład kodu
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 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:

Przykład kodu
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:

Przykład kodu
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 shows what to file and how the review works.
  • Sender registration. A United States local number needs 10DLC registration before it sends SMS. A United States toll-free number needs toll-free verification instead. SMS sender IDs 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.
  • 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.
  • 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.

Before the agent acts on a received email, check dkim_pass and spf_pass on the event, as 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:

Przykład kodu
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:

Przykład kodu
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 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