> ## Documentation Index
> Fetch the complete documentation index at: https://openmail-docs-reputation-lifecycle-webhooks.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://github.com/openmailsh/skills/blob/main/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

```bash theme={"theme":{"light":"github-light","dark":"dark-plus"}}
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:

```json theme={"theme":{"light":"github-light","dark":"dark-plus"}}
{
  "id": "msg_...",
  "threadId": "thr_...",
  "inboxId": "inb_...",
  "direction": "outbound",
  "createdAt": "2024-01-01T00:00:00.000Z"
}
```

### Threads

```bash theme={"theme":{"light":"github-light","dark":"dark-plus"}}
# 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:

```json theme={"theme":{"light":"github-light","dark":"dark-plus"}}
{
  "id": "thr_...",
  "inboxId": "inb_...",
  "subject": "Re: Hello",
  "lastMessageAt": "2024-01-01T00:00:00.000Z",
  "isRead": false,
  "messageCount": 3
}
```

### Messages

```bash theme={"theme":{"light":"github-light","dark":"dark-plus"}}
# 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:

```json theme={"theme":{"light":"github-light","dark":"dark-plus"}}
{
  "id": "msg_...",
  "threadId": "thr_...",
  "inboxId": "inb_...",
  "fromAddr": "Alice <alice@example.com>",
  "toAddr": "agent@openmail.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

```bash theme={"theme":{"light":"github-light","dark":"dark-plus"}}
# 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:

```json theme={"theme":{"light":"github-light","dark":"dark-plus"}}
{
  "id": "inb_...",
  "address": "support@example.openmail.sh",
  "displayName": "Support",
  "createdAt": "2024-01-01T00:00:00.000Z"
}
```

### Status & diagnostics

```bash theme={"theme":{"light":"github-light","dark":"dark-plus"}}
openmail status
```

Shows API connection, default inbox, and bridge status.

***

## REST API

All endpoints require `Authorization: Bearer `.

### POST /v1/inboxes/{id}/send

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

```http theme={"theme":{"light":"github-light","dark":"dark-plus"}}
POST /v1/inboxes/{id}/send
Authorization: Bearer om_live_...
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.
* **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/{id}/threads

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

### PATCH /v1/threads/{id}

```http theme={"theme":{"light":"github-light","dark":"dark-plus"}}
PATCH /v1/threads/{id}
Content-Type: application/json

{ "is_read": true }
```

### GET /v1/threads/{id}/messages

Returns messages in a thread, sorted oldest-first.

### GET /v1/inboxes/{id}/messages

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

### GET /v1/attachments/{messageId}/{filename}

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:

```bash theme={"theme":{"light":"github-light","dark":"dark-plus"}}
python3 -c "import uuid; print(uuid.uuid4())"
```