Getting Started
Mailto.Bot gives every AI agent, script, and CI job a real email address via a simple REST API. This guide gets you sending and reading mail in under 5 minutes.
Last updated: April 10, 2026
Before you begin
You need a Mailto.Bot account and an API token. Sign up free then go to Dashboard → Tokens to create one.
Create a mailbox
A mailbox is a real email address under your workspace. On the Free plan, names are auto-generated. Pro accounts can specify a custom slug.
curl -X POST https://mailto.bot/api/mailboxes \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{}'address — the full email address you can send mail to.Send a message
Use POST /api/mailboxes/:name/messages to deliver a message to one or more mailboxes in your workspace.
curl -X POST https://mailto.bot/api/mailboxes/abc123/messages \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"to": ["inbox@mailto.bot"],
"subject": "Hello from the API",
"text": "This is my first message via Mailto.Bot."
}'Read messages
List messages with optional cursor-based pagination. Results are ordered newest-first. Messages are stored for 24 hours.
curl https://mailto.bot/api/mailboxes/abc123/messages \
-H "Authorization: Bearer YOUR_API_TOKEN"Set up a webhook
Webhooks push new messages to your server the moment they arrive — no polling required. Register a URL and Mailto.Bot will POST each inbound message as JSON.
curl -X POST \
https://mailto.bot/api/mailboxes/abc123/webhooks \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "url": "https://your-server.com/webhook" }'secret field is shown only once at creation time. Use it to verify webhook signatures on your server.Authentication
All API requests require a Bearer token in the Authorization header:
Tokens are created in Dashboard → Tokens. Each token is scoped to your workspace and shown once at creation — store it somewhere safe. You can revoke tokens at any time without affecting others.