# AgentMail — Orthogonal API

> Pay-per-use API on Orthogonal. Each call is billed to your Orthogonal balance.
> Base API: `https://api.orthogonal.com/v1/run` · [llms.txt](https://orthogonal.com/llms.txt) · [browse all APIs](https://orthogonal.com/discover)

Programmatic email for AI agents. Create inboxes, send/receive emails, manage threads and drafts. Inboxes cost $2/month. Inboxes inactive for 30+ days are automatically deleted.

**Verified:** yes

## Access

**Run API:** `POST https://api.orthogonal.com/v1/run`
**Auth:** `Authorization: Bearer $ORTHOGONAL_API_KEY`
Get an API key at https://orthogonal.com/dashboard/settings/api-keys

Every call goes through the unified Run API: send the API `slug`, the endpoint `path`, and the `query`/`body` parameters. The response is `{ "success": true, "price": "<usd>", "data": { ... } }`.

## Endpoints

### Get Draft

Get a specific draft including its full content, recipients, and attachments.

`GET /v0/inboxes/{inbox_id}/drafts/{draft_id}`

**Cost:** Free

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `inbox_id` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |
| `draft_id` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |

```bash
# Replace {inbox_id}, {draft_id} in "path" with real values before sending
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"agentmail","path":"/v0/inboxes/{inbox_id}/drafts/{draft_id}","method":"GET"}'
```

### Send Draft

Send an existing draft as an email. The draft is converted to a sent message and deleted from drafts. Returns the message_id and thread_id.

`POST /v0/inboxes/{inbox_id}/drafts/{draft_id}/send`

**Cost:** Free

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `inbox_id` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |
| `draft_id` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |
| `labels` | array | No | Labels to apply to the sent message (overrides draft labels). |

```bash
# Replace {inbox_id}, {draft_id} in "path" with real values before sending
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"agentmail","path":"/v0/inboxes/{inbox_id}/drafts/{draft_id}/send","body":{"labels":"<array>"}}'
```

### Delete Draft

Permanently delete a draft. Important: pass method: "DELETE" in your run request.

`DELETE /v0/inboxes/{inbox_id}/drafts/{draft_id}`

**Cost:** Free

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `inbox_id` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |
| `draft_id` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |

```bash
# Replace {inbox_id}, {draft_id} in "path" with real values before sending
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"agentmail","path":"/v0/inboxes/{inbox_id}/drafts/{draft_id}","method":"DELETE"}'
```

### Get Inbox

Get details of a specific inbox including display name, creation date, and metadata.

`GET /v0/inboxes/{inbox_id}`

**Cost:** Free

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `inbox_id` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |

```bash
# Replace {inbox_id} in "path" with real values before sending
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"agentmail","path":"/v0/inboxes/{inbox_id}","method":"GET"}'
```

### Update Inbox

Update an existing inbox display name or client ID.

`PATCH /v0/inboxes/{inbox_id}`

**Cost:** Free

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `inbox_id` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |
| `display_name` | string | No | Display name: Display Name <username@domain.com>. |
| `client_id` | string | No | Client ID of inbox. |

```bash
# Replace {inbox_id} in "path" with real values before sending
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"agentmail","path":"/v0/inboxes/{inbox_id}","method":"PATCH","body":{"display_name":"<string>","client_id":"<string>"}}'
```

### Get Thread

Get a thread and all its messages. Returns the full conversation including message bodies, timestamps, and metadata.

`GET /v0/inboxes/{inbox_id}/threads/{thread_id}`

**Cost:** Free

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `inbox_id` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |
| `thread_id` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |

```bash
# Replace {inbox_id}, {thread_id} in "path" with real values before sending
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"agentmail","path":"/v0/inboxes/{inbox_id}/threads/{thread_id}","method":"GET"}'
```

### Delete Thread

Move a thread to trash, or permanently delete if already trashed. Important: pass method: "DELETE" in your run request.

`DELETE /v0/inboxes/{inbox_id}/threads/{thread_id}`

**Cost:** Free

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `inbox_id` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |
| `thread_id` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |
| `permanent` | boolean | No | If true, permanently delete instead of moving to trash. |

```bash
# Replace {inbox_id}, {thread_id} in "path" with real values before sending
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"agentmail","path":"/v0/inboxes/{inbox_id}/threads/{thread_id}","method":"DELETE","query":{"permanent":"<boolean>"}}'
```

### Delete Inbox

Permanently delete an inbox and all its contents. Important: pass method: "DELETE" in your run request to distinguish from Get Inbox.

`DELETE /v0/inboxes/{inbox_id}`

**Cost:** Free

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `inbox_id` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |

```bash
# Replace {inbox_id} in "path" with real values before sending
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"agentmail","path":"/v0/inboxes/{inbox_id}","method":"DELETE"}'
```

### Get Raw Message

Get the original raw RFC 2822 email content including all headers, MIME parts, and encoded attachments.

`GET /v0/inboxes/{inbox_id}/messages/{message_id}/raw`

**Cost:** Free

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `inbox_id` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |
| `message_id` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |

```bash
# Replace {inbox_id}, {message_id} in "path" with real values before sending
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"agentmail","path":"/v0/inboxes/{inbox_id}/messages/{message_id}/raw","method":"GET"}'
```

### Update Message

Update labels on a message (e.g., mark as read, archive, star).

`PATCH /v0/inboxes/{inbox_id}/messages/{message_id}`

**Cost:** Free

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `inbox_id` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |
| `message_id` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |
| `labels` | array | No | Array of label strings to set on the message (e.g., ["read", "starred"]). Replaces existing labels. |

```bash
# Replace {inbox_id}, {message_id} in "path" with real values before sending
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"agentmail","path":"/v0/inboxes/{inbox_id}/messages/{message_id}","method":"PATCH","body":{"labels":"<array>"}}'
```

### Create Draft

Create a new draft in an inbox. The draft can be edited later and sent with Send Draft.

`POST /v0/inboxes/{inbox_id}/drafts`

**Estimated cost:** $0.01

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `inbox_id` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |
| `to` | array | No | Recipient email addresses as an array of strings. |
| `cc` | array | No | CC recipient email addresses. |
| `bcc` | array | No | BCC recipient email addresses. |
| `reply_to` | array | No | Reply-to addresses. |
| `subject` | string | No | Email subject line. |
| `text` | string | No | Plain text body of the draft. |
| `html` | string | No | HTML body of the draft. |
| `labels` | array | No | Labels to tag the draft. |
| `attachments` | array | No | Array of attachment objects: {filename, content_type, content (base64)} or {filename, content_type, url}. |
| `headers` | object | No | Custom email headers as key-value pairs. |

```bash
# Replace {inbox_id} in "path" with real values before sending
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"agentmail","path":"/v0/inboxes/{inbox_id}/drafts","body":{"to":"<array>","cc":"<array>","bcc":"<array>","reply_to":"<array>","subject":"<string>","text":"<string>","html":"<string>","labels":"<array>","attachments":"<array>","headers":"<object>"}}'
```

### Reply To Message

Reply to a specific message. Automatically sets In-Reply-To and References headers for proper threading.

`POST /v0/inboxes/{inbox_id}/messages/{message_id}/reply`

**Estimated cost:** $0.01

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `inbox_id` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |
| `message_id` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |
| `to` | array | No | Override recipient(s). Defaults to the original sender if omitted. |
| `cc` | array | No | CC recipient address(es). |
| `bcc` | array | No | BCC recipient address(es). |
| `reply_to` | array | No | Reply-to address(es) if different from the inbox. |
| `reply_all` | boolean | No | If true, reply to all original recipients. |
| `text` | string | No | Plain text body of the reply. |
| `html` | string | No | HTML body of the reply. |
| `labels` | array | No | Labels to tag the reply message. |
| `attachments` | array | No | Array of attachment objects: {filename, content_type, content (base64)} or {filename, content_type, url}. |
| `headers` | object | No | Custom email headers as key-value pairs. |

```bash
# Replace {inbox_id}, {message_id} in "path" with real values before sending
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"agentmail","path":"/v0/inboxes/{inbox_id}/messages/{message_id}/reply","body":{"to":"<array>","cc":"<array>","bcc":"<array>","reply_to":"<array>","reply_all":"<boolean>","text":"<string>","html":"<string>","labels":"<array>","attachments":"<array>","headers":"<object>"}}'
```

### List Drafts

List all drafts in an inbox. Returns draft metadata including subject, recipients, and timestamps.

`GET /v0/inboxes/{inbox_id}/drafts`

**Cost:** Free

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `inbox_id` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |
| `limit` | integer | No | Max number of drafts to return. |
| `page_token` | string | No | Token from previous response for fetching the next page. |
| `labels` | string | No | Filter by label. |
| `before` | string | No | Only return drafts before this ISO 8601 timestamp. |
| `after` | string | No | Only return drafts after this ISO 8601 timestamp. |
| `ascending` | boolean | No | If true, sort oldest first. Default is newest first. |

```bash
# Replace {inbox_id} in "path" with real values before sending
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"agentmail","path":"/v0/inboxes/{inbox_id}/drafts","method":"GET","query":{"limit":"<integer>","page_token":"<string>","labels":"<string>","before":"<string>","after":"<string>","ascending":"<boolean>"}}'
```

### Send Message

Send an email message from an inbox. At least one recipient (to, cc, or bcc) is required. Returns the message_id and thread_id. Replace {inbox_id} directly in the path with the full inbox email (e.g., /v0/inboxes/myagent@agentmail.to/messages/send).

`POST /v0/inboxes/{inbox_id}/messages/send`

**Estimated cost:** $0.01

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `inbox_id` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |
| `to` | array | No | Recipient email address(es). At least one of to, cc, or bcc is required. Can be a string or array of strings. |
| `cc` | array | No | CC recipient email address(es). String or array of strings. |
| `bcc` | array | No | BCC recipient email address(es). String or array of strings. |
| `reply_to` | array | No | Reply-to address(es) if different from the inbox address. |
| `subject` | string | No | Email subject line. |
| `text` | string | No | Plain text body. Provide text, html, or both. |
| `html` | string | No | HTML body. Provide text, html, or both. |
| `labels` | array | No | Array of label strings to tag the sent message. |
| `attachments` | array | No | Array of attachment objects: {filename: string, content_type: string, content: string (base64)} or {filename: string, content_type: string, url: string}. |
| `headers` | object | No | Custom email headers as key-value pairs (e.g., {"X-Custom": "value"}). |

```bash
# Replace {inbox_id} in "path" with real values before sending
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"agentmail","path":"/v0/inboxes/{inbox_id}/messages/send","body":{"to":"<array>","cc":"<array>","bcc":"<array>","reply_to":"<array>","subject":"<string>","text":"<string>","html":"<string>","labels":"<array>","attachments":"<array>","headers":"<object>"}}'
```

### List Threads

List all email threads in an inbox, ordered by most recent. Supports pagination and filtering.

`GET /v0/inboxes/{inbox_id}/threads`

**Cost:** Free

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `inbox_id` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |
| `limit` | integer | No | Max number of threads to return (default varies by API). |
| `page_token` | string | No | Token from previous response for fetching the next page. |
| `labels` | string | No | Filter by label (e.g., unread, sent, trash). |
| `before` | string | No | Only return threads before this ISO 8601 timestamp. |
| `after` | string | No | Only return threads after this ISO 8601 timestamp. |
| `ascending` | boolean | No | If true, sort oldest first. Default is newest first. |
| `include_spam` | boolean | No | Include threads labeled as spam. |
| `include_blocked` | boolean | No | Include threads from blocked senders. |
| `include_trash` | boolean | No | Include threads in trash. |

```bash
# Replace {inbox_id} in "path" with real values before sending
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"agentmail","path":"/v0/inboxes/{inbox_id}/threads","method":"GET","query":{"limit":"<integer>","page_token":"<string>","labels":"<string>","before":"<string>","after":"<string>","ascending":"<boolean>","include_spam":"<boolean>","include_blocked":"<boolean>","include_trash":"<boolean>"}}'
```

### Update Draft

Update an existing draft. Only the fields you include will be changed; omitted fields are left unchanged.

`PATCH /v0/inboxes/{inbox_id}/drafts/{draft_id}`

**Cost:** Free

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `inbox_id` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |
| `draft_id` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |
| `to` | array | No | Updated recipient email addresses. |
| `cc` | array | No | Updated CC recipients. |
| `bcc` | array | No | Updated BCC recipients. |
| `reply_to` | array | No | Updated reply-to addresses. |
| `subject` | string | No | Updated subject line. |
| `text` | string | No | Updated plain text body. |
| `html` | string | No | Updated HTML body. |
| `labels` | array | No | Updated labels. |
| `attachments` | array | No | Updated attachments: {filename, content_type, content (base64)} or {filename, content_type, url}. |
| `headers` | object | No | Updated custom email headers. |

```bash
# Replace {inbox_id}, {draft_id} in "path" with real values before sending
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"agentmail","path":"/v0/inboxes/{inbox_id}/drafts/{draft_id}","method":"PATCH","body":{"to":"<array>","cc":"<array>","bcc":"<array>","reply_to":"<array>","subject":"<string>","text":"<string>","html":"<string>","labels":"<array>","attachments":"<array>","headers":"<object>"}}'
```

### Forward Message

Forward a message to new recipients. Includes the original message content and any attachments.

`POST /v0/inboxes/{inbox_id}/messages/{message_id}/forward`

**Estimated cost:** $0.01

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `inbox_id` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |
| `message_id` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |
| `to` | array | No | Recipient email address(es) to forward to. At least one of to, cc, or bcc is required. |
| `cc` | array | No | CC recipient address(es). |
| `bcc` | array | No | BCC recipient address(es). |
| `reply_to` | array | No | Reply-to address(es) if different from the inbox. |
| `subject` | string | No | Override subject. Defaults to "Fwd: [original subject]". |
| `text` | string | No | Additional plain text to prepend before the forwarded content. |
| `html` | string | No | Additional HTML to prepend before the forwarded content. |
| `labels` | array | No | Labels to tag the forwarded message. |
| `attachments` | array | No | Additional attachments: {filename, content_type, content (base64)} or {filename, content_type, url}. |
| `headers` | object | No | Custom email headers as key-value pairs. |

```bash
# Replace {inbox_id}, {message_id} in "path" with real values before sending
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"agentmail","path":"/v0/inboxes/{inbox_id}/messages/{message_id}/forward","body":{"to":"<array>","cc":"<array>","bcc":"<array>","reply_to":"<array>","subject":"<string>","text":"<string>","html":"<string>","labels":"<array>","attachments":"<array>","headers":"<object>"}}'
```

### Reply All Message

Reply to all recipients of a message. Includes all original To and CC recipients automatically.

`POST /v0/inboxes/{inbox_id}/messages/{message_id}/reply-all`

**Estimated cost:** $0.01

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `inbox_id` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |
| `message_id` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |
| `to` | array | No | Additional recipient(s) beyond the original ones. |
| `cc` | array | No | Additional CC recipients. |
| `bcc` | array | No | BCC recipient address(es). |
| `reply_to` | array | No | Reply-to address(es) if different from the inbox. |
| `text` | string | No | Plain text body of the reply. |
| `html` | string | No | HTML body of the reply. |
| `labels` | array | No | Labels to tag the reply message. |
| `attachments` | array | No | Array of attachment objects: {filename, content_type, content (base64)} or {filename, content_type, url}. |
| `headers` | object | No | Custom email headers as key-value pairs. |

```bash
# Replace {inbox_id}, {message_id} in "path" with real values before sending
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"agentmail","path":"/v0/inboxes/{inbox_id}/messages/{message_id}/reply-all","body":{"to":"<array>","cc":"<array>","bcc":"<array>","reply_to":"<array>","text":"<string>","html":"<string>","labels":"<array>","attachments":"<array>","headers":"<object>"}}'
```

### Get Message

Get a specific message including headers, body (text and HTML), attachments, and metadata.

`GET /v0/inboxes/{inbox_id}/messages/{message_id}`

**Cost:** Free

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `inbox_id` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |
| `message_id` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |

```bash
# Replace {inbox_id}, {message_id} in "path" with real values before sending
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"agentmail","path":"/v0/inboxes/{inbox_id}/messages/{message_id}","method":"GET"}'
```

### List Messages

List all messages in an inbox, ordered by most recent. Supports pagination and filtering by labels or time range.

`GET /v0/inboxes/{inbox_id}/messages`

**Cost:** Free

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `inbox_id` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |
| `limit` | integer | No | Max number of messages to return. |
| `page_token` | string | No | Token from previous response for fetching the next page. |
| `labels` | string | No | Filter by label (e.g., unread, sent, trash). |
| `before` | string | No | Only return messages before this ISO 8601 timestamp. |
| `after` | string | No | Only return messages after this ISO 8601 timestamp. |
| `ascending` | boolean | No | If true, sort oldest first. Default is newest first. |
| `include_spam` | boolean | No | Include messages labeled as spam. |
| `include_blocked` | boolean | No | Include messages from blocked senders. |
| `include_trash` | boolean | No | Include messages in trash. |

```bash
# Replace {inbox_id} in "path" with real values before sending
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"agentmail","path":"/v0/inboxes/{inbox_id}/messages","method":"GET","query":{"limit":"<integer>","page_token":"<string>","labels":"<string>","before":"<string>","after":"<string>","ascending":"<boolean>","include_spam":"<boolean>","include_blocked":"<boolean>","include_trash":"<boolean>"}}'
```

### Create Inbox

Create a new email inbox. Inboxes cost $2/month. Inboxes with no API activity for 30+ days are automatically deleted. Any request using the inbox resets the inactivity timer. Returns an inbox_id in email format (e.g., myagent@agentmail.to) used for all subsequent operations. If username is omitted, a random one is generated.

`POST /v0/inboxes`

**Estimated cost:** $2

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `username` | string | No | Local part of the email address (e.g., myagent becomes myagent@agentmail.to). Randomly generated if omitted. |
| `domain` | string | No | Email domain. Must be a verified custom domain. Defaults to agentmail.to. |
| `display_name` | string | No | Human-readable name shown in the From header (e.g., My Agent <myagent@agentmail.to>). |
| `client_id` | string | No | Your own identifier to associate with this inbox. |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"agentmail","path":"/v0/inboxes","body":{"username":"<string>","domain":"<string>","display_name":"<string>","client_id":"<string>"}}'
```

---

Full details and an interactive quickstart: https://orthogonal.com/discover/agentmail