Messages API

Send email, list inbox messages, and retrieve individual messages.

GET /v1/mailboxes/:id/messages

GET/v1/mailboxes/:id/messages

List messages for a mailbox with optional filters.

Query parameters

Name	Type	Description
direction	"INBOUND" \| "OUTBOUND"	Filter by direction
threadId	string	Filter by thread UUID
since	string	ISO 8601 timestamp — only messages after this time
limit	number	1-100 (default 50)
offset	number	Pagination offset (default 0)

response — 200 OK

{
  "messages": [
    {
      "id": "msg_abc123",
      "direction": "INBOUND",
      "messageId": "<[email protected]>",
      "fromAddress": "[email protected]",
      "toAddresses": ["[email protected]"],
      "subject": "Hello",
      "bodyText": "Hi there!",
      "bodyHtml": "<p>Hi there!</p>",
      "status": "RECEIVED",
      "hasAttachments": false,
      "threadId": "thr_abc123",
      "createdAt": "2026-03-11T12:00:00.000Z",
      "attachments": []
    }
  ]
}

POST /v1/mailboxes/:id/messages

POST/v1/mailboxes/:id/messages

Send an email from the specified mailbox. The message is sent immediately via Amazon SES.

Request body

Name	Type	Description
to*	string[]	Recipient email addresses
cc	string[]	CC recipients
subject*	string	Email subject (1-998 chars)
bodyText*	string	Plain text body
bodyHtml	string	HTML body
inReplyTo	string	RFC 5322 Message-ID to reply to
attachments	string[]	Attachment UUIDs from /v1/attachments
headers	object	Custom headers (x-custom-* or x-robotomail-* only)

curl

curl -X POST https://api.robotomail.com/v1/mailboxes/mbx_abc123/messages \
  -H "Authorization: Bearer $ROBOTOMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["[email protected]"],
    "subject": "Project update",
    "bodyText": "Here is the latest status...",
    "bodyHtml": "<p>Here is the latest status...</p>"
  }'

response — 201 Created

{
  "message": {
    "id": "msg_def456",
    "direction": "OUTBOUND",
    "fromAddress": "[email protected]",
    "toAddresses": ["[email protected]"],
    "subject": "Project update",
    "status": "SENT",
    "sesMessageId": "0102abc...",
    "threadId": "thr_def456",
    "createdAt": "2026-03-11T12:30:00.000Z"
  }
}

Errors

400 — Invalid input, mailbox inactive, address is on the suppression list
403 — Email not verified, or SES sandbox mode (recipient not verified)
413 — Message exceeds 10 MB SES limit
429 — Daily send limit exceeded or SES throttling

GET /v1/mailboxes/:id/messages/:msgId

GET/v1/mailboxes/:id/messages/:msgId

Retrieve a single message with full body content and attachment metadata.

Message statuses

QUEUED — Message is queued for sending
SENT — Accepted by SES for delivery
DELIVERED — Confirmed delivered to recipient's mail server
BOUNCED — Permanently bounced (address doesn't exist or rejected)
COMPLAINED — Recipient reported the message as spam
FAILED — Sending failed (SES error)
RECEIVED — Inbound message stored successfully