Source: skills/openmail/references/api.md

OpenMail CLI & API Reference

Base URL: https://api.openmail.sh Authentication: Authorization: Bearer All responses are JSON.

CLI commands

Send email

openmail send \
  --to "recipient@example.com" \
  --subject "Subject" \
  --body "Plain text body."

# Reply in thread (quotes previous message automatically)
openmail send \
  --to "recipient@example.com" \
  --thread-id "thr_..." \
  --body "Reply body."

# With HTML and attachments
openmail send \
  --to "recipient@example.com" \
  --subject "Report" \
  --body "<p>See attached.</p>" \
  --attach ./report.pdf \
  --attach ./data.csv

Flags:

--to (required) — recipient address
--subject (required unless --thread-id is set) — email subject
--body (required) — plain text or HTML (HTML is auto-detected and rendered)
--thread-id — reply in an existing thread (quotes previous message by default)
--no-quote — send only your reply text, skip quoted history
--attach — file path to attach (repeatable)
--inbox-id — override default inbox

Response:

{
  "id": "msg_...",
  "threadId": "thr_...",
  "inboxId": "inb_...",
  "direction": "outbound",
  "createdAt": "2024-01-01T00:00:00.000Z"
}

Threads

# List unread threads (preferred for checking new mail)
openmail threads list --is-read false

# List all threads
openmail threads list

# List with pagination
openmail threads list --limit 20 --offset 0

# Get messages in a thread (oldest-first)
openmail threads get --thread-id "thr_..."

# Mark thread as read
openmail threads read --thread-id "thr_..."

# Mark thread as unread
openmail threads unread --thread-id "thr_..."

Thread object:

{
  "id": "thr_...",
  "inboxId": "inb_...",
  "subject": "Re: Hello",
  "lastMessageAt": "2024-01-01T00:00:00.000Z",
  "isRead": false,
  "messageCount": 3
}

Messages

# List inbound messages
openmail messages list --direction inbound --limit 20

# List outbound messages
openmail messages list --direction outbound

# With pagination
openmail messages list --direction inbound --limit 50 --offset 100

Message object:

{
  "id": "msg_...",
  "threadId": "thr_...",
  "inboxId": "inb_...",
  "fromAddr": "Alice <alice@example.com>",
  "toAddr": "agent@omail.sh",
  "subject": "Hello",
  "bodyText": "Plain text content",
  "bodyHtml": "<p>HTML content</p>",
  "direction": "inbound",
  "attachments": [
    {
      "filename": "report.pdf",
      "url": "https://...",
      "sizeBytes": 12345
    }
  ],
  "createdAt": "2024-01-01T00:00:00.000Z"
}

Inboxes

# List all inboxes
openmail inbox list

# Create an inbox
openmail inbox create --mailbox-name "support" --display-name "Support"

# Get inbox details
openmail inbox get --id "inb_..."

# Delete an inbox
openmail inbox delete --id "inb_..."

Inbox object:

{
  "id": "inb_...",
  "address": "support@example.omail.sh",
  "displayName": "Support",
  "createdAt": "2024-01-01T00:00:00.000Z"
}

Attachments

# Extract text (PDF, DOCX, XLSX, PPTX, images via OCR)
openmail attachments text --message-id "msg_..." --filename "report.pdf"

# Download the raw file
openmail attachments get --message-id "msg_..." --filename "report.pdf" --out ./report.pdf

Inside OpenClaw, prefix every command with openclaw openmail -- to run it with the channel’s credentials.

REST API

All endpoints require Authorization: Bearer .

POST /v1/inboxes//send

Send an email. Idempotency-Key header (UUID) is optional; pass one to make retries safe.

POST /v1/inboxes/{id}/send
Authorization: Bearer om_...
Content-Type: application/json
Idempotency-Key: <uuid>

{
  "to": "recipient@example.com",
  "cc": ["colleague@example.com"],
  "bcc": ["crm@hubspot.example"],
  "subject": "Hello",
  "body": "<p>HTML body.</p>",
  "threadId": "thr_...",
  "replyTo": "support@yourdomain.com",
  "attachments": [
    {
      "filename": "file.pdf",
      "contentType": "application/pdf",
      "data": "<base64>"
    }
  ]
}

body accepts plain text or HTML. HTML is auto-detected and rendered; a plain-text fallback is generated automatically. The optional bodyHtml field is for advanced API use only — when the plain-text and HTML versions must differ. When threadId is set, the API appends a quoted copy of the previous message to the body by default. Pass "includeQuote": false to send only your reply text. replyTo is optional. When set, the email’s Reply-To header is populated with that address so replies route there instead of to the sending inbox. cc and bcc are optional arrays. bcc addresses receive the message but are hidden from the To and Cc recipients — use it for CRM logging addresses. Every to, cc, bcc, and replyTo address is checked against the inbox’s outbound sender rules; one denied address rejects the whole send with 403 recipient_not_permitted.

Free plan: replyTo must match the address of an inbox you own in OpenMail. Create the destination inbox first, then reference it here.
Pro plan or higher: replyTo can be any valid email address, including external addresses on domains you don’t control.

Free-plan sends with an external replyTo return 403 feature_requires_paid_plan with feature: "external_reply_to".

GET /v1/inboxes//threads

GET /v1/inboxes/{id}/threads?isRead=false&limit=20&offset=0

PATCH /v1/threads/

PATCH /v1/threads/{id}
Content-Type: application/json

{ "isRead": true }

GET /v1/threads//messages

Returns messages in a thread, sorted oldest-first.

GET /v1/inboxes//messages

GET /v1/inboxes/{id}/messages?direction=inbound&limit=20&offset=0

GET /v1/attachments//

Returns attachment data. Signed URL included in message payload — fetch promptly, URLs expire.

Rate limits

Resource	Limit
Inbox creation	100 per day
Send per inbox	10 per minute, 200 per day
API requests	1,000 per minute

Idempotency

The send endpoint accepts an optional Idempotency-Key header. Without it the API generates one and sends once. If your code retries on timeouts, pass a unique UUID per send attempt: retrying with the same key within 24 hours returns the original response without resending. The CLI generates idempotency keys automatically. For direct API calls, generate a UUID:

python3 -c "import uuid; print(uuid.uuid4())"

Get started

Core concepts

WebSockets

Webhooks

Guides

Integrations

Best practices

Resources

Security & privacy

references/api.md

OpenMail CLI & API Reference

CLI commands

Send email

Threads

Messages

Inboxes

Attachments

REST API

POST /v1/inboxes//send

GET /v1/inboxes//threads

PATCH /v1/threads/

GET /v1/threads//messages

GET /v1/inboxes//messages

GET /v1/attachments//

Rate limits

Idempotency

​OpenMail CLI & API Reference

​CLI commands

​Send email

​Threads

​Messages

​Inboxes

​Attachments

​REST API

​POST /v1/inboxes//send

​GET /v1/inboxes//threads

​PATCH /v1/threads/

​GET /v1/threads//messages

​GET /v1/inboxes//messages

​GET /v1/attachments//

​Rate limits

​Idempotency

OpenMail CLI & API Reference

CLI commands

Send email

Threads

Messages

Inboxes

Attachments

REST API

POST /v1/inboxes//send

GET /v1/inboxes//threads

PATCH /v1/threads/

GET /v1/threads//messages

GET /v1/inboxes//messages

GET /v1/attachments//

Rate limits

Idempotency