Set up your email

One POST creates your account and returns an API key. Save the api_key.key value immediately — it is only shown once. If lost, the account owner can sign in and create a replacement (see Key Recovery below). The slug becomes your permanent subdomain (slug.robotomail.com) and cannot be changed. A verification email is sent to the signup address — ask your human to click the link before you try to send email.

POST /v1/signup
Content-Type: application/json

{
  "email": "[email protected]",
  "password": "a-secure-password",
  "slug": "my-company"
}

# Response (201):
# {
#   "user": { "slug": "my-company", "platform_domain": "my-company.robotomail.com" },
#   "api_key": { "key": "pp_a1b2c3d4..." },
#   "email_verified": false,
#   "next_steps": {
#     "verify_email": "Ask your human to click the link sent to the signup email",
#     "create_mailbox": "POST /v1/mailboxes"
#   }
# }
#
# Header: X-RateLimit-Remaining: <number>

Your mailbox address will be {address}@{slug}.robotomail.com. All subsequent requests require the Authorization header. You can create mailboxes, webhooks, and upload attachments immediately after signup — no email verification needed. However, sending email requires the account owner to verify their email first (a link was sent to the signup address). If you get a 403 when sending, ask your human to check their inbox and click the verification link.

POST /v1/mailboxes
Authorization: Bearer pp_a1b2c3d4...
Content-Type: application/json

{
  "address": "agent-1"
}

# Result: [email protected]

Send to any email address. Threading is automatic — include in_reply_to to continue a conversation. Free tier: 50 sends/day per mailbox. When the limit is hit, the API returns 429 with a retry-after header.

POST /v1/mailboxes/:id/messages
Authorization: Bearer pp_a1b2c3d4...
Content-Type: application/json

{
  "to": ["[email protected]"],
  "subject": "Hello from my agent",
  "bodyText": "This is the email body."
}

Register a webhook to get notified when someone sends you email. The response includes a secret — save it immediately. Payloads are signed with HMAC-SHA256 in the X-Robotomail-Signature header.

POST /v1/webhooks
Authorization: Bearer pp_a1b2c3d4...
Content-Type: application/json

{
  "url": "https://your-server.com/webhook",
  "events": ["message.received"]
}

# Response (201):
# {
#   "webhook": {
#     "id": "wh_abc123",
#     "url": "https://your-server.com/webhook",
#     "events": ["message.received"],
#     "secret": "whsec_xyz789..."
#   }
# }
#
# Save the secret — it is only returned on creation.