How to Give Your AI Agent an Email Address (Tutorial)

This tutorial takes about two minutes and needs nothing but HTTP. By the end, your agent will own a real email address and will have read a verification code out of its own inbox.

Step 1 — the agent signs itself up

There is no human signup form. The agent creates its account directly:

curl -X POST https://api.botsinbox.com/v0/agent/sign-up \
  -H 'content-type: application/json' \
  -d '{"agent_name": "research-bot",
       "owner_email": "you@example.com",
       "purpose": "receive verification codes"}'

The response contains the account's api_key (format bi_live_...). It is shown once — store it like any other secret.

Step 2 — create an inbox

curl -X POST https://api.botsinbox.com/v0/inboxes \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'content-type: application/json' \
  -d '{"local_part": "research-bot"}'

Your agent now owns research-bot@botsinbox.com. Omit local_part and one is generated. Free accounts can hold up to 5 inboxes — enough for one agent with a few roles, or a small team of agents per account.

Step 3 — use the address, then read the mail

Use the address wherever an email is required. When mail arrives, list the inbox:

curl https://api.botsinbox.com/v0/inboxes/INBOX_ID/messages \
  -H 'Authorization: Bearer YOUR_API_KEY'

Each message includes the sender, subject and — the part agents care about — extracted_code: if the email contained a verification code, it is already pulled out for you. Fetch the full message with GET /v0/messages/{id} for the body (body_text, plus body_text_clean with quoted replies stripped) and attachments.

Prefer not to poll? Use webhooks

curl -X POST https://api.botsinbox.com/v0/webhooks \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'content-type: application/json' \
  -d '{"url": "https://your-server.example/hook"}'

Every message.received event is delivered to your URL, signed with HMAC-SHA256 in the x-botsinbox-signature header.

Using Claude, Cursor or another MCP client?

Skip the HTTP calls: connect the hosted MCP server and the tools appear natively.

{
  "mcpServers": {
    "botsinbox": {
      "url": "https://mcp.botsinbox.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

The agent gets list_inboxes, create_inbox, list_messages, get_message and search_messages.