Robotomaildocs
HomeGet started

Quickstart

Go from zero to sending your first email in under 5 minutes.

Prerequisites

You need curl (or any HTTP client) and a terminal. No SDKs, packages, or configuration files required.

1. Create an account

Sign up with your email, a password, and a slug. The slug becomes your platform email address: slug@robotomail.co.

curl
curl -X POST https://api.robotomail.com/v1/signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "password": "your-password",
    "slug": "myagent"
  }'

The response includes your API key. Save it now — it cannot be retrieved later.

response
{
  "user": { "id": "clx1a2b3c0000abcd1234efgh", "slug": "myagent", "plan": "free", "platform_email": "myagent@robotomail.co" },
  "api_key": { "key": "rm_a1b2c3...", "prefix": "rm_a1b2c", "name": "default" },
  "mailbox": { "id": "a1b2c3d4-5678-4def-abcd-111111111111", "fullAddress": "myagent@robotomail.co", "status": "ACTIVE" },
  "daily_send_limit": 10,
  "monthly_send_limit": 10,
  "email_verified": false,
  "next_steps": { "verify_email": "...", "add_payment": "Optional: POST /v1/billing/upgrade for a checkout URL to increase limits", "add_domain": "POST /v1/domains", "send_email": "POST /v1/mailboxes/:id/messages" }
}

2. Save your API key

Export the key as an environment variable for the remaining steps:

shell
export ROBOTOMAIL_API_KEY="rm_a1b2c3..."

3. Verify your email

Check the inbox of the email you signed up with and click the verification link. Verification activates the Free plan: 1 mailbox, 10 sends and 10 receives per month. Exchange mail only between your agent and your verified email address. Upgrade to email anyone. No credit card, no expiry. Allowances reset on the first of each month (UTC). Upgrade for higher limits or a custom domain. Product calls return 403 (email verification required) before verification. Mail outside the Free plan rules or above the receive limit is discarded.

4. Your mailbox is ready

A default mailbox (myagent@robotomail.co) was created automatically when you signed up. List your mailboxes to confirm:

curl
curl https://api.robotomail.com/v1/mailboxes \
  -H "Authorization: Bearer $ROBOTOMAIL_API_KEY"
response
{
  "mailboxes": [
    {
      "id": "a1b2c3d4-5678-4def-abcd-111111111111",
      "fullAddress": "myagent@robotomail.co",
      "status": "ACTIVE",
      "dailySendLimit": 10,
      "monthlySendCount": 0,
      "monthlySendLimit": 10
    }
  ]
}

5. Send your first email

Send an email from your new mailbox to your verified signup address. Replace MAILBOX_ID with the id from the previous step.

curl
curl -X POST https://api.robotomail.com/v1/mailboxes/MAILBOX_ID/messages \
  -H "Authorization: Bearer $ROBOTOMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["you@example.com"],
    "subject": "Hello from my agent",
    "bodyText": "This email was sent by an AI agent via Robotomail."
  }'

The email is sent immediately via Resend. The response includes the message ID and status.

6. Check your inbox

Poll for inbound messages, set up a webhook to receive them in real time, or use SSE streaming (GET /v1/events) for real-time events without a public endpoint.

curl
curl https://api.robotomail.com/v1/mailboxes/MAILBOX_ID/messages?direction=INBOUND \
  -H "Authorization: Bearer $ROBOTOMAIL_API_KEY"

Next steps