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"
}

Status & diagnostics

openmail status

Shows API connection, default inbox, and bridge status.

REST API

All endpoints require Authorization: Bearer .

POST /v1/inboxes//send

Send an email. Requires Idempotency-Key header (UUID).

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

{
  "to": "recipient@example.com",
  "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.

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?is_read=false&limit=20&offset=0

PATCH /v1/threads/

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

{ "is_read": 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 requires an Idempotency-Key header. Use 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

Status & diagnostics

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

​Status & diagnostics

​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

Status & diagnostics

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