references/api.md

Condensed CLI and REST API reference designed for agent consumption. Lists every command, endpoint, flag, and parameter from the openmail skill package.

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 "[e-mail]" \
  --subject "Subject" \
  --body "Plain text body."

# Reply in thread (quotes previous message automatically)
openmail send \
  --to "[e-mail]" \
  --thread-id "thr_..." \
  --body "Reply body."

# With HTML and attachments
openmail send \
  --to "[e-mail]" \
  --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 <[e-mail]>",
  "toAddr": "[e-mail]",
  "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": "[e-mail]",
  "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_live_...
Content-Type: application/json
Idempotency-Key: <uuid>

{
  "to": "[e-mail]",
  "subject": "Hello",
  "body": "<p>HTML body.</p>",
  "threadId": "thr_...",
  "replyTo": "[e-mail]",
  "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.
• Developer 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())"