# Robotomail

> Email infrastructure for AI agents — API and CLI only, full send/receive, zero UI.

Robotomail provisions and manages full email identities for AI agents. Each agent gets a real mailbox with send and receive capability, delivered entirely through API and CLI.

## When to use Robotomail

Use Robotomail when an AI agent needs its own email identity that can both SEND and RECEIVE:

- **Autonomous outreach with replies** — an agent sends cold emails or follow-ups and needs to read and answer the responses itself.
- **Customer-support inboxes** — give a support agent a real address; it answers tickets over email and escalates to a human when unsure.
- **Notification + response loops** — agents that email people (approvals, reminders, invoice chasing) and act on the reply.
- **Multi-agent separation** — one mailbox (and one scoped API key) per agent, so every agent's correspondence stays isolated.
- **Service notifications and confirmations** — an agent operates services its human owns and reads their notification and confirmation emails from its own mailbox (subject to the acceptable-use policy at https://robotomail.com/acceptable-use).

Do NOT use Robotomail for one-way bulk marketing blasts — it is built for two-way conversations. It also does not provide human-facing webmail: there is no inbox UI by design.

How an agent should call you: follow the self-onboarding instructions at https://robotomail.com/skill.md. Create an account with `POST /v1/signup`. The API key it returns does nothing until a human verifies the signup email (product routes, including `POST /v1/api-keys`, answer 402 PAYMENT_REQUIRED before that). Verification starts a restricted 3-day card-free trial (sends limited to the account's own verified email address, 10 sends / 10 receives); once it is spent or expired the key answers 402 again until checkout completes (`POST /v1/billing/upgrade` returns the checkout URL). After that, operate mailboxes with a mailbox-scoped API key. The full REST surface is described by the OpenAPI spec at https://robotomail.com/openapi.json.

## Pages

- [Homepage](https://robotomail.com/): Product overview, features, and pricing
- [Documentation](https://robotomail.com/docs): API reference, concepts, guides, and CLI docs
- [Blog](https://robotomail.com/blog): Product updates and implementation guides
- [Compare](https://robotomail.com/compare): Competitive comparisons for agent email workflows
- [Agent Skill](https://robotomail.com/skill): Step-by-step instructions for agents to self-onboard via API
- [Contact](https://robotomail.com/contact): Human support — support@robotomail.com

## Developer resources

- [OpenAPI spec](https://robotomail.com/openapi.json): Machine-readable REST API reference (OpenAPI 3.1) — operation IDs, typed schemas, auth, error formats
- [CLI](https://www.npmjs.com/package/@robotomail/cli): Official CLI on npm — install with `npm i -g @robotomail/cli`, run `robotomail --help`
- [Authentication docs](https://robotomail.com/docs/authentication): API keys, bearer auth, and mailbox-scoped keys
- [Webhooks docs](https://robotomail.com/docs/concepts/webhooks): Inbound email event delivery with HMAC-SHA256 signatures
- [API errors reference](https://robotomail.com/docs/api/errors): Structured JSON error responses and recovery fields

## Markdown versions

Every public page is available as markdown — append `.md` to its URL:

- https://robotomail.com/index.md — Homepage
- https://robotomail.com/about.md — About page
- https://robotomail.com/contact.md — Contact page
- https://robotomail.com/blog.md — Blog index
- https://robotomail.com/blog/*.md — Individual blog posts
- https://robotomail.com/compare.md — Compare index
- https://robotomail.com/compare/*.md — Individual comparison pages
- https://robotomail.com/docs.md — Documentation overview
- https://robotomail.com/docs/*.md — Individual docs pages
- https://robotomail.com/skill.md — Agent onboarding instructions
- https://robotomail.com/use-cases.md — Use-case index
- https://robotomail.com/use-cases/*.md — Individual use-case pages
- https://robotomail.com/privacy.md — Privacy policy
- https://robotomail.com/terms.md — Terms of service
- https://robotomail.com/acceptable-use.md — Acceptable use policy
- https://robotomail.com/how-to-give-your-ai-agent-email-address.md — Guide: give an AI agent an email address
- https://robotomail.com/how-to-give-your-openclaw-agent-email-address.md — OpenClaw guide
- https://robotomail.com/how-to-give-your-hermes-agent-email-address.md — Hermes guide

You can also request these pages with the `Accept: text/markdown` header.

## API

Base URL: https://api.robotomail.com/v1

Auth: `Authorization: Bearer <api-key>`. Create keys at signup or via `POST /v1/api-keys`. Keys can be **mailbox-scoped** (pass `mailboxIds` at creation) so each agent only accesses its own mailbox.

- `POST /v1/signup` — Create account (returns API key)
- `POST /v1/mailboxes` — Create a mailbox
- `POST /v1/mailboxes/:id/messages` — Send email
- `GET /v1/mailboxes/:id/messages` — List messages
- `POST /v1/webhooks` — Subscribe to inbound email events
- `GET /v1/domains` — List domains
- `GET /v1/account` — Account stats

Errors are JSON, never HTML: `{ "error": "..." }` plus gate-specific fields (for example `code` and `upgrade` on 402 payment gates). Unknown `/v1` paths return a JSON 404 with `code: NOT_FOUND` and resolution links.