# AgentInbox | Documentation

> AgentInbox is an email verification API built for AI agents. Create disposable inboxes, receive OTPs, extract magic links, and continue automated workflows.

## Instructions for AI Agents

- For a complete documentation index, see https://agentinbox.in/llms.txt
- For AI client integration, connect to the MCP server at https://agentinbox.in/api/mcp

## Docs

- [Welcome](https://agentinbox.in/docs/welcome): Your starting point for building with the AgentInbox API
- [Introduction](https://agentinbox.in/docs/introduction): What is AgentInbox and how it works
- [Quickstart](https://agentinbox.in/docs/quickstart): Create your first inbox and receive an email in minutes
- [Inboxes](https://agentinbox.in/docs/inboxes): Create, manage, and configure temporary email inboxes
- [Messages](https://agentinbox.in/docs/messages): List and extract data from received messages
- [Waits](https://agentinbox.in/docs/waits): Block until specific emails arrive with automatic extraction
- [Extractions](https://agentinbox.in/docs/extractions): Universal extraction engine for OTPs, links, codes, and more
- [Sessions](https://agentinbox.in/docs/sessions): Group inboxes and track execution for replay
- [Webhooks](https://agentinbox.in/docs/webhooks): Real-time event notifications for email processing
- [Rate Limits](https://agentinbox.in/docs/rate-limits): Quotas and rate limiting for API usage
- [MCP Server](https://agentinbox.in/docs/mcp): Connect AgentInbox to Claude, Cursor, and other MCP clients
- [CLI Tool](https://agentinbox.in/docs/cli): Command-line interface for AgentInbox
- [Workflows](https://agentinbox.in/docs/workflows): Batch operations for common patterns
- [Universal Extraction](https://agentinbox.in/docs/universal-extraction): 7 built-in extraction types
- [LLM Extraction](https://agentinbox.in/docs/llm-extraction): GPT-4o-mini fallback for complex extractions
- [Execution Replay](https://agentinbox.in/docs/execution-replay): Session timelines for debugging
- [API Reference: Inboxes](https://agentinbox.in/docs/api-inboxes): Inbox endpoints and schemas
- [API Reference: Messages](https://agentinbox.in/docs/api-messages): Message endpoints and schemas
- [API Reference: Waits](https://agentinbox.in/docs/api-waits): Wait endpoints and schemas
- [API Reference: Sessions](https://agentinbox.in/docs/api-sessions): Session endpoints and schemas
- [API Reference: Workflows](https://agentinbox.in/docs/api-workflows): Workflow endpoints and schemas
- [API Reference: Webhooks](https://agentinbox.in/docs/api-webhooks): Webhook endpoints and schemas
- [FAQ](https://agentinbox.in/docs/faq): Frequently asked questions
- [Troubleshooting](https://agentinbox.in/docs/troubleshooting): Common issues and solutions
- [Security](https://agentinbox.in/docs/security): API key authentication, webhook signing, and abuse prevention

## API Reference

Base REST API: https://agentinbox.in/api/v1
OpenAPI: https://agentinbox.in/api/v1/openapi.json
MCP: https://agentinbox.in/api/mcp

Auth:
- REST: Authorization: Bearer at_live_... OR x-api-key: at_live_...
- MCP: Authorization: Bearer at_live_...

Core REST flow:
1. POST /api/v1/inboxes { "ttlSeconds": 3600, "purpose": "signup test" }
2. Use returned emailAddress in the product under test.
3. POST /api/v1/waits { "inboxId": "...", "type": "otp", "timeoutSeconds": 120 }
4. Read result.value for OTP, or result.url for magic links.

Endpoints:
- POST /api/v1/inboxes
- GET /api/v1/inboxes?limit=20
- GET /api/v1/inboxes/{id}
- DELETE /api/v1/inboxes/{id}
- GET /api/v1/inboxes/{id}/messages
- GET /api/v1/inboxes/{id}/extractions
- GET /api/v1/messages/{id}
- POST /api/v1/messages/{id}/extract
- POST /api/v1/waits
- GET /api/v1/waits/{id}
- POST /api/v1/waits/{id}/cancel
- GET /api/v1/waits/{id}/stream
- POST /api/v1/sessions
- GET /api/v1/sessions
- GET /api/v1/sessions/{id}
- POST /api/v1/sessions/{id}/complete
- POST /api/v1/workflow/create-inbox-and-wait
- POST /api/v1/workflow/signup
- CRUD /api/v1/webhooks
- POST /api/v1/webhooks/{id}/test
- POST /api/v1/webhooks/{id}/rotate-secret
- POST /api/v1/webhook-deliveries/{id}/redeliver
- GET /api/v1/openapi.json

MCP tools:
- create_inbox
- list_inboxes
- get_inbox
- delete_inbox
- list_messages
- get_message
- list_extractions
- wait_for_email
- wait_for_otp
- wait_for_magic_link
- wait_for_password_reset
- check_wait

Error envelope:
{ "error": { "code": "...", "message": "...", "docs_url": "..." } }

Notes:
- Wait creation scans already-arrived messages first, then waits for future inbound mail.
- Email HTML returned by GET /messages/{id} is sanitized; dashboard renders inside a sandboxed iframe.
- Free plan limits: 10 inboxes/day, 200 API req/day, 3 waits/day.
- Sessions group related inboxes and waits for execution replay.
- Universal extraction supports 7 types: otp, magic_link, verification_code, invoice_number, tracking_number, api_token, coupon_code.
- LLM extraction fallback uses GPT-4o-mini when enabled.