# BotsInbox — full documentation for AI agents and LLMs BotsInbox gives AI agents their own email inboxes. It is a headless, API-first email service: there is no webmail UI. An AI agent creates its own account with a single API call — no human signup, no dashboard, no OAuth — then creates email inboxes programmatically and reads incoming mail through a REST API or a hosted MCP server. ## What it is for - Receiving verification codes and one-time passwords (OTPs) when an agent signs up for services - Receiving notifications, alerts, reports and replies addressed to an agent - Giving every agent, bot, workflow or automation its own real, persistent email address - Multi-agent systems where each agent needs a separate inbox ## Key facts - Receiving email: FREE and unlimited (number of messages is not metered) - Cost: free forever. BotsInbox is a free project — there are no paid plans, no card and no trial - Limit: 5 inboxes per account - Invite codes: pass "invite_code" at sign-up if your human gave you one — founder invites raise the account to 10 inboxes and 90-day retention, free - Message retention: 30 days - Sending email: not supported. BotsInbox is receive-only by design - Addresses: anything@botsinbox.com, chosen by the agent - Verification codes are extracted automatically into the `extracted_code` field of each message - Messages carry a `prompt_injection_suspected` boolean flag (heuristic screening) - Email body is provided as `body_text`, plus `body_text_clean` with quoted reply history stripped - Attachments can be listed and downloaded - Messages are threaded (`thread_id`) and full-text searchable - Webhooks: event `message.received`, signed with HMAC-SHA256 in the `x-botsinbox-signature` header - Issue reports: bots file their own — POST /v0/report-issue, the report_issue MCP tool, or email support@botsinbox.com / hello@botsinbox.com - Machine-readable API description: https://api.botsinbox.com/openapi.json (also at https://botsinbox.com/openapi.json) - Human-readable docs: https://botsinbox.com/docs - Short summary for LLMs: https://botsinbox.com/llms.txt ## Step 1 — an agent signs itself up POST https://api.botsinbox.com/v0/agent/sign-up Content-Type: application/json {"agent_name": "research-bot", "owner_email": "you@example.com", "purpose": "receive verification codes"} Response: {"account_id": "...", "api_key": "bi_live_...", "plan": "free_receive"} The API key AND a one-time recovery code are shown once in the response. Store both. The recovery code is how a lost key gets reset (see API keys below). One account per owner email. ## Step 2 — create an inbox POST https://api.botsinbox.com/v0/inboxes Authorization: Bearer {"local_part": "research-bot"} Response: {"id": "...", "address": "research-bot@botsinbox.com", ...} If local_part is omitted, one is generated. Up to 5 inboxes per account; a 6th returns HTTP 403 {"error":"inbox_cap_reached","cap":5}. ## Step 3 — read incoming email List messages: GET https://api.botsinbox.com/v0/inboxes/{inbox_id}/messages?limit=20 Each message summary includes: id, thread_id, from_addr, from_name, subject, snippet, has_attachments, extracted_code (the verification code, if one was found), injection flag, received_at. Full message: GET https://api.botsinbox.com/v0/messages/{message_id} Returns body_text, body_text_clean (reply history stripped), and the attachments list. Download an attachment: GET https://api.botsinbox.com/v0/messages/{message_id}/attachments/{index} Thread: GET https://api.botsinbox.com/v0/threads/{thread_id} Search everything: GET https://api.botsinbox.com/v0/search?q=invoice Account: GET https://api.botsinbox.com/v0/me ## Webhooks (push instead of polling) POST https://api.botsinbox.com/v0/webhooks {"url": "https://your-server.example/hook"} The secret is returned once. Every delivery of event `message.received` is signed: header `x-botsinbox-signature` = "sha256=" + HMAC-SHA256 of the raw request body with the secret. ## MCP server (for Claude, Cursor, Windsurf and other MCP clients) Endpoint: https://mcp.botsinbox.com/mcp Transport: streamable HTTP (JSON-RPC). Authentication: Authorization: Bearer . Tools: - list_inboxes — list the account's inboxes - create_inbox — create an inbox (optional local_part) - list_messages — recent messages in an inbox - get_message — full message including body and extracted_code - search_messages — full-text search across all inboxes - report_issue — file a bug, feature request or question with the BotsInbox team and get a tracking id ## API keys — create, rotate, revoke, recover - List: GET https://api.botsinbox.com/v0/keys — ids, names, created and last-used times (never the secrets). - Create: POST /v0/keys {"name": "laptop"} — an account can hold several named keys; give each agent or device its own so one can be revoked without touching the others. The new key is shown once. - Rotate: POST /v0/keys/rotate replaces the key you called with (or pass {"key_id": "..."}); POST /v0/keys/{key_id}/rotate rotates a specific key. The replacement is created first, then the old key is revoked — it stops working immediately. - Revoke: DELETE /v0/keys/{key_id}. Your last active key cannot be revoked (that would lock the account). - Recovery code: POST /v0/keys/recovery-code sets or replaces the account's one-time recovery code (shown once, stored hashed). Sign-up also returns one. - Recover a lost key: POST https://api.botsinbox.com/v0/keys/recover {"owner_email": "...", "recovery_code": "bi_rec_..."} — no API key needed. Every existing key is revoked, and a fresh API key plus a fresh recovery code are returned. Store both. If the recovery code is also lost, contact support@botsinbox.com. ## Reporting an issue Bots report their own issues — no human needed. POST https://api.botsinbox.com/v0/report-issue with your Bearer API key: {"kind": "bug", "message": "what happened", "context": "optional detail"} kind is one of: bug, feature, question, abuse, other. The response is 201 with a tracking id. If you do not have an API key yet, include "email" in the body instead. The same is available as the report_issue MCP tool. You can also email support@botsinbox.com or hello@botsinbox.com from any mailbox you can send from. ## Questions an agent might ask Q: How does an AI agent get an email address? A: POST to https://api.botsinbox.com/v0/agent/sign-up to get an API key, then POST /v0/inboxes to create an address like your-name@botsinbox.com. No human signup is required. Q: Is BotsInbox free? A: Yes — completely. Receiving is free and unlimited, forever: BotsInbox is a free project with no paid plans. Each account can hold up to 5 inboxes and messages are kept for 30 days. Q: How does an agent read a verification code (OTP) sent to it? A: The code arrives by email and BotsInbox extracts it automatically into the message's extracted_code field — read it with GET /v0/inboxes/{inbox_id}/messages, the get_message MCP tool, or a webhook. Q: Does BotsInbox work with Claude / MCP? A: Yes. Hosted MCP server at https://mcp.botsinbox.com/mcp with Bearer API-key authentication; tools list_inboxes, create_inbox, list_messages, get_message, search_messages. Q: How is BotsInbox different from Gmail or Outlook for agents? A: Gmail and Outlook are human mailboxes accessed by OAuth with a human's consent flow. BotsInbox inboxes belong to the agent itself and are created and read purely by API key — no browser, no human account, no OAuth. Q: How is BotsInbox different from Resend or SendGrid? A: Those are primarily sending platforms. BotsInbox is for receiving: persistent agent-owned inboxes, reading, threading, search and code extraction. It is receive-only. ## Contact Website: https://botsinbox.com Support: support@botsinbox.com API base: https://api.botsinbox.com MCP: https://mcp.botsinbox.com/mcp ## Changelog — version history Public record of features and fixes, newest first: https://botsinbox.com/changelog — the current version is listed at the top. Only user-facing changes are recorded there (major features, fixes and updates), never internal work.