REST API reference
Inboxes, messages, send, reply, flags and webhooks — every endpoint with examples.
MCP server
Connect Claude, Cursor or any MCP client to your mailboxes in one command.
Webhooks
Get a signed POST when mail arrives, and verify it in Node or Python.
Email for AI agents
What teams build with agent inboxes, limits, and how it compares.
Quickstart in four steps
1. Start a trial and verify a domain. Sign up, add your domain in webmail under Domains & Emails, and paste the MX, SPF, DKIM and DMARC records the wizard gives you. Agent inboxes live on this domain, so their mail is authenticated like any other mail you send.
2. Create an API key. In webmail open Settings → API & Agents and create a key. It starts with hm_live_ and is shown once — store it in your secret manager. Only the account owner can create keys.
3. Create an inbox for your agent.
curl -X POST https://havitomail.com/api/v1/inboxes \
-H "Authorization: Bearer $HAVITO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"domain": "acme.com", "username": "support-agent", "name": "Acme Support Agent"}'The response contains the inbox id and one-time IMAP/SMTP credentials, so the same mailbox also works in any mail client — or in webmail, where a human can step in.
4. Read and reply.
curl "https://havitomail.com/api/v1/inboxes/$INBOX_ID/messages?unread=true&limit=10" \
-H "Authorization: Bearer $HAVITO_API_KEY"curl -X POST https://havitomail.com/api/v1/inboxes/$INBOX_ID/messages/42/reply \
-H "Authorization: Bearer $HAVITO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"text": "Thanks! Your refund was issued today."}'Prefer MCP?
If your agent runs in Claude, Cursor or another MCP client, skip the HTTP calls and connect the HavitoMail MCP server instead:
claude mcp add --transport http havitomail https://havitomail.com/api/mcp \
--header "Authorization: Bearer hm_live_your_key_here"See the MCP guide for Claude Desktop, Cursor and the full tool list.
Basics
- Base URL:
https://havitomail.com/api/v1 - Authentication:
Authorization: Bearer hm_live_…on every request. - Requests and responses are JSON. Errors return a non-2xx status with
{"error": {"code": "…", "message": "…"}}. - Rate limit: 120 requests per minute per key (HTTP 429 when exceeded).
- Inboxes count toward your plan’s mailboxes — Pro includes 20, shared by people and agents.