API Reference

Full reference for every Mailto.Bot REST endpoint. All requests require a Bearer token unless noted otherwise.

Last updated: April 10, 2026

Authentication

Include your API token in every request: Authorization: Bearer YOUR_API_TOKEN. Create tokens in Dashboard → Tokens.

Mailboxes

A mailbox is a real email address under your workspace. Messages are stored for 24 hours.

POST/api/mailboxes

Creates a new mailbox. On the Free plan the name is auto-generated. Pro accounts may supply a custom name slug.

Request body (JSON)

Name	Type	Description
`name`	`string`	Custom mailbox slug (Pro only). Omit to auto-generate.

Response 201

Name	Type	Description
`id`*	`string`	Unique mailbox ID.
`name`*	`string`	Mailbox slug used in API paths.
`address`*	`string`	Full email address.
`messageCount`*	`number`	Current message count in Redis.
`createdAt`*	`string`	ISO 8601 creation timestamp.

Errors: 400 invalid JSON · 401 unauthenticated · 403 custom name requires Pro · 409 name taken · 422 invalid name · 429 rate limited

cURL

curl -X POST https://mailto.bot/api/mailboxes \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

GET/api/mailboxes

Returns all mailboxes for the authenticated workspace, ordered by creation date (newest first), with live message counts from Redis.

Response 200 — array of

Name	Type	Description
`id`*	`string`	Mailbox ID.
`name`*	`string`	Slug used in API paths.
`address`*	`string`	Full email address.
`messageCount`*	`number`	Messages currently in inbox.
`createdAt`*	`string`	ISO 8601 timestamp.

Errors: 401 unauthenticated · 429 rate limited

cURL

curl https://mailto.bot/api/mailboxes \
  -H "Authorization: Bearer YOUR_API_TOKEN"

DELETE/api/mailboxes/:name

Permanently deletes a mailbox and purges all its messages from Redis. This action is irreversible.

Path parameters

Name	Type	Description
`name`*	`string`	Mailbox slug.

Returns 204 No Content on success.

Errors: 401 unauthenticated · 404 not found · 429 rate limited

cURL

curl -X DELETE https://mailto.bot/api/mailboxes/abc123 \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Messages

Messages are stored in Redis with a 24-hour TTL. Large attachments are offloaded to Cloud Storage and served via signed URLs.

Attachment Handling

Inbound emails with attachments are automatically parsed. The attachments array is always present on every message object (empty array when there are none).

Receiving attachments

Each attachment object contains:

Field	Type	Description
`filename`	`string`	Original file name.
`contentType`	`string`	MIME type, e.g. "application/pdf".
`size`	`number`	File size in bytes.
`signedUrl`	`string\|null`	Signed GCS URL (files >1 MiB), valid 1 hour. null for smaller inline files.

Inbound limit: 25 MiB per email.

Sending attachments

Include an attachments array in the send-message body. Each entry:

Field	Type	Description
`filename`	`string`	File name shown to the recipient.
`contentType`	`string`	MIME type, e.g. "image/png".
`data`	`string`	Base64-encoded file bytes.

Send limit: 10 MiB total payload (all attachments combined).

Subaddress routing (tag field)

Every mailbox supports the standard +tag subaddress format. Sending to support+ticket42@acme.mailto.bot delivers to the support mailbox and sets message.tag = "ticket42". Use tags to route by ticket ID, user ID, or any other label — no extra mailboxes needed.

Receive

// Attachment object on a received message
{
  "filename": "invoice-2026-04.pdf",
  "contentType": "application/pdf",
  "size": 512000,
  // signedUrl is present for files >1 MiB (GCS-offloaded), valid 1 hour
  "signedUrl": "https://storage.googleapis.com/mailtobot-attachments/..."
}

// Small files (<1 MiB) are stored inline in Redis —
// signedUrl will be null for those.

POST/api/mailboxes/:name/messages

Sends a message from the specified mailbox to one or more recipients. All to and cc addresses must belong to your workspace.

Path parameters

Name	Type	Description
`name`*	`string`	Sender mailbox slug.

Request body (JSON)

Name	Type	Description
`to`*	`string[]`	Recipient email addresses (workspace mailboxes).
`subject`*	`string`	Message subject line.
`text`	`string`	Plain-text body.
`html`	`string`	HTML body.
`from`	`string`	Sender display name (defaults to mailbox address).
`cc`	`string[]`	CC recipients (workspace mailboxes only).

Response 201

Name	Type	Description
`messageId`*	`string`	Unique ID of the created message.
`deliveredTo`*	`string[]`	Addresses that received the message.

Errors: 400 bad request · 401 unauthenticated · 404 mailbox not found · 413 attachment too large · 422 validation failed

cURL

curl -X POST \
  https://mailto.bot/api/mailboxes/abc123/messages \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["inbox@mailto.bot"],
    "subject": "Hello",
    "text": "Your message here."
  }'

GET/api/mailboxes/:name/messages

Lists messages in a mailbox. Returns newest-first with cursor-based pagination.

Query parameters

Name	Type	Description
`limit`	`number`	Max results per page. Default 20, max 100.
`after`	`string`	Pagination cursor from a previous response's nextCursor.
`since`	`string`	ISO 8601 timestamp — return only messages after this time.

Response 200

Name	Type	Description
`messages`*	`Message[]`	Array of message objects (see GET /:id for shape).
`nextCursor`*	`string \| null`	Cursor for the next page; null if no more results.
`total`*	`number`	Total messages currently in inbox.

Errors: 400 invalid query · 401 unauthenticated · 404 mailbox not found

cURL

curl "https://mailto.bot/api/mailboxes/abc123/messages?limit=20" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

GET/api/mailboxes/:name/messages/:id

Fetches a single message by ID. Attachment URLs are signed and valid for 1 hour.

Response 200 — message object

Name	Type	Description
`id`*	`string`	Message ID.
`from`*	`string`	Sender address.
`to`*	`string[]`	Recipient addresses.
`subject`*	`string`	Subject line.
`text`	`string`	Plain-text body.
`html`	`string`	HTML body.
`attachments`	`object[]`	Attachments with filename, contentType, size, url.
`receivedAt`*	`string`	ISO 8601 receipt timestamp.

Errors: 401 unauthenticated · 404 not found · 429 rate limited

cURL

curl https://mailto.bot/api/mailboxes/abc123/messages/msg_id \
  -H "Authorization: Bearer YOUR_API_TOKEN"

DELETE/api/mailboxes/:name/messages/:id

Deletes a message and removes any associated Cloud Storage attachments. Idempotent — returns 204 even if the message was already deleted.

Errors: 401 unauthenticated · 429 rate limited

cURL

curl -X DELETE \
  https://mailto.bot/api/mailboxes/abc123/messages/msg_id \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Webhooks

Register a URL and Mailto.Bot will POST each inbound message to it immediately. The secret returned at creation is shown only once.

For the full guide including payload format, retry behaviour, and ngrok testing, see the Webhooks Guide.

POST/api/mailboxes/:name/webhooks

Registers a new webhook for the mailbox. The secret is shown only once — store it immediately.

Request body (JSON)

Name	Type	Description
`url`*	`string`	HTTPS (or HTTP for development) URL to POST events to.

Response 201

Name	Type	Description
`id`*	`string`	Webhook ID.
`mailboxId`*	`string`	Parent mailbox ID.
`url`*	`string`	Registered URL.
`active`*	`boolean`	Whether the webhook is enabled.
`secret`*	`string`	Signing secret — shown once only.
`createdAt`*	`string`	ISO 8601 timestamp.

Errors: 400 invalid URL · 401 unauthenticated · 404 mailbox not found

cURL

curl -X POST \
  https://mailto.bot/api/mailboxes/abc123/webhooks \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://your-server.com/webhook" }'

GET/api/mailboxes/:name/webhooks

Lists all webhooks for the mailbox. The secret field is omitted from list responses.

Errors: 401 unauthenticated · 404 mailbox not found

cURL

curl https://mailto.bot/api/mailboxes/abc123/webhooks \
  -H "Authorization: Bearer YOUR_API_TOKEN"

DELETE/api/mailboxes/:name/webhooks/:id

Deletes a webhook. No further events will be delivered to the registered URL.

Errors: 401 unauthenticated · 404 not found

cURL

curl -X DELETE \
  https://mailto.bot/api/mailboxes/abc123/webhooks/wh_id \
  -H "Authorization: Bearer YOUR_API_TOKEN"

API Tokens

Bearer tokens authenticate all API requests. The raw token value is shown only once at creation. Tokens are workspace-scoped.

GET/api/tokens

Lists all active tokens for the workspace.

Response 200 — array of

Name	Type	Description
`id`*	`string`	Token ID.
`name`*	`string`	Human-readable label.
`prefix`*	`string`	First 8 chars of the token (safe to display).
`lastUsedAt`	`string\|null`	ISO 8601 timestamp of last use.
`createdAt`*	`string`	ISO 8601 creation timestamp.

Errors: 401 unauthenticated

cURL

curl https://mailto.bot/api/tokens \
  -H "Authorization: Bearer YOUR_API_TOKEN"

POST/api/tokens

Creates a new API token. The full token value is returned only once — store it immediately.

Request body (JSON)

Name	Type	Description
`name`*	`string`	Human-readable label for the token.

Response 201

Name	Type	Description
`id`*	`string`	Token ID.
`name`*	`string`	Label.
`prefix`*	`string`	Safe display prefix.
`token`*	`string`	Full token value — shown once only.
`createdAt`*	`string`	ISO 8601 timestamp.

Errors: 400 missing name · 401 unauthenticated · 500 encryption failure

cURL

curl -X POST https://mailto.bot/api/tokens \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "my-token" }'

DELETE/api/tokens/:id

Revokes an API token immediately. Any in-flight requests using the token will receive 401 errors.

Errors: 401 unauthenticated · 404 token not found

cURL

curl -X DELETE https://mailto.bot/api/tokens/tok_id \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Error Codes

All errors return JSON with an error field describing the problem.

Status	Name	Meaning
`400`	Bad Request	Malformed JSON, missing required field, or invalid parameter value.
`401`	Unauthorized	Missing or invalid Bearer token. Check the Authorization header.
`403`	Forbidden	Action not permitted for your plan or role (e.g. custom names require Pro).
`404`	Not Found	The resource (mailbox, message, token) does not exist or belongs to another workspace.
`409`	Conflict	Resource already exists — e.g. custom mailbox name already taken.
`413`	Payload Too Large	Attachment exceeds the per-recipient size limit.
`422`	Unprocessable	Request body is valid JSON but fails business-logic validation.
`429`	Too Many Requests	API rate limit exceeded. Slow down and retry with exponential back-off.
`503`	Service Unavailable	Transient infrastructure issue. Retry after a short delay.

Webhooks Guide →

Payload format, retry behaviour, and ngrok testing.

MCP Integration →

Connect Claude Desktop, Cursor, or Windsurf in one step.