Robotomail lets an AI agent send, receive, and react to email programmatically. It is API-first email infrastructure for autonomous agents, assistants, and workflows.

Use Robotomail when you want an agent to:

• send outbound email, reminders, updates, or follow-ups
• read inbound email from a real inbox
• react to incoming email via webhooks or real-time SSE events
• reply in existing threads using normal email semantics
• use a hosted robotomail.co address or a custom domain

Best-fit use cases

1. Agent support inbox

Give your agent a real inbox so it can classify, summarize, draft, or reply to incoming support emails.

2. Outbound follow-ups and reminders

Let an agent send reminders, nudges, receipts, booking confirmations, or outbound follow-ups from its own mailbox.

3. Real-time email triggers

Subscribe to inbound email events with webhooks or SSE so your agent can wake up and act immediately.

Fast start

If the user is new to Robotomail, the fastest path is:

• Sign up at https://robotomail.com or create an account via POST /v1/signup
• Create or list a mailbox with GET /v1/mailboxes or POST /v1/mailboxes
• Send a test email with POST /v1/mailboxes/{id}/messages
• Read inbound email with GET /v1/mailboxes/{id}/messages?direction=INBOUND
• Subscribe to inbound events via webhook or SSE

Authentication

All requests require an API key in the Authorization header:

Authorization: Bearer 

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

If the user doesn't have an API key yet, they can sign up at https://robotomail.com or you can create an account via POST /v1/signup.

Quick Reference — What Can I Do?

Task	Method	Endpoint
Send an email	POST	/v1/mailboxes/{id}/messages
List inbox messages	GET	/v1/mailboxes/{id}/messages?direction=INBOUND
Read a specific message	GET	/v1/mailboxes/{id}/messages/{msgId}
List conversation threads	GET	/v1/mailboxes/{id}/threads
Read a thread	GET	/v1/mailboxes/{id}/threads/{tid}
List mailboxes	GET	/v1/mailboxes
Create a mailbox	POST	/v1/mailboxes
Add a custom domain	POST	/v1/domains
Verify domain DNS	POST	/v1/domains/{id}/verify
Set up a webhook	POST	/v1/webhooks
Stream events with SSE	GET	/v1/events
Upload an attachment	POST	/v1/attachments (multipart)
Check account & usage	GET	/v1/account

For full endpoint details including request/response schemas, read references/api-reference.md.

Webhooks vs SSE

Use webhooks when Robotomail should push events to your public HTTPS endpoint.

Use SSE when the agent wants a live event stream over a single long-lived connection, for example when running a local listener or agent loop.

If the user says things like "stream inbound mail", "listen for new messages", or "real-time inbox events", prefer SSE.

Decision Tree — Common Tasks

"Send an email"

• List mailboxes: GET /v1/mailboxes — find the mailbox to send from
• Send: POST /v1/mailboxes/{id}/messages with to, subject, bodyText (and optionally bodyHtml)
• To reply to an existing message, include inReplyTo with the original message's messageId header value

"Check my inbox" / "Read my email"

• List mailboxes: GET /v1/mailboxes
• Fetch inbound messages: GET /v1/mailboxes/{id}/messages?direction=INBOUND
• Read a specific message: GET /v1/mailboxes/{id}/messages/{msgId}

"Reply to an email"

• Read the original message to get its messageId field
• Send reply: POST /v1/mailboxes/{id}/messages with inReplyTo set to the original's messageId value
• Threading is automatic — the reply joins the same thread

"Set up email for a new domain"

• Add domain: POST /v1/domains with {"domain": "example.com"}
• Read the dnsRecords from the response — tell the user to configure these at their DNS provider
• After DNS is configured, verify: POST /v1/domains/{id}/verify
• Once verified, create a mailbox: POST /v1/mailboxes with {"address": "agent", "domainId": ""}

"Set up a webhook for incoming email"

• Create webhook: POST /v1/webhooks with url and events: ["message.received"]
• Save the secret from the response, it is shown only once
• Verify deliveries with X-Robotomail-Signature header (HMAC-SHA256 of payload using secret)

See references/webhook-verification.md for signature verification code.

"Listen for incoming email in real time" / "Use SSE"

• Connect to GET /v1/events
• Filter or react to message.received, message.delivered, message.bounced, and message.complaint
• Use SSE when the agent wants a live stream instead of public webhook delivery

"Send an email with an attachment"

• Upload the file: POST /v1/attachments (multipart/form-data, field name file, max 25MB)
• Note the returned attachment id
• Send the message with attachments: [""]

Key Constraints

• Daily send limits: 100/day (free), 500–2,000/day (paid, varies by tier) per mailbox — resets at midnight UTC
• Monthly send limits: 5,000/month (free), 15,000/month (Developer), unlimited (Growth, Scale) per mailbox
• Velocity limits: 30 messages/min per mailbox, 60 messages/min per account — returns 429 if exceeded
• Bounce rate: Must stay below 3% over a 7-day rolling window (minimum 50 messages). Exceeding this auto-suspends the mailbox.
• Complaint rate: Must stay below 0.05% over a 7-day rolling window (minimum 50 messages). Exceeding this auto-suspends the mailbox.
• Attachment size: Max 25MB per file
• Storage: 1GB (free), 10GB (Developer), 25GB (Growth), 100GB (Scale)
• Free tier: 3 mailboxes on robotomail.co only
• Paid plans start at $19/mo (Developer): 10+ mailboxes, custom domains

If a send returns 429, the mailbox has hit its daily/monthly limit or velocity limit. Tell the user and suggest slowing down or upgrading if on the free plan.

Error Handling

All errors return {"error": "message"} with standard HTTP status codes:

• 401 — Missing or invalid API key
• 403 — Account suspended or scoped key accessing a restricted resource. When suspended, response includes { "suspended": true, "reason": "bounce_rate_exceeded" }. Tell the user to contact support@robotomail.com.
• 404 — Resource not found
• 429 — Rate limit, velocity limit, or send quota exceeded
• 413 — Attachment too large

Tips

• Always use bodyText for the plain-text version. Add bodyHtml only when rich formatting is needed.
• Use threads (GET /v1/mailboxes/{id}/threads/{tid}) to see full conversation history before replying.
• When listing messages, use since parameter (ISO-8601) to fetch only recent messages.
• Suppression list (GET /v1/suppressions) contains bounced/complained addresses — check before sending to addresses that previously failed.