> ## 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.

# API Overview

> OpenMail REST API reference overview — base URL, JSON request/response format, HTTP status codes, and standardized error payloads explained.

## Base URL

```
https://api.openmail.sh
```

## Request format

* All request bodies are JSON (`Content-Type: application/json`)
* All responses are JSON
* Dates are ISO 8601 (`2026-02-24T10:00:00.000Z`)
* IDs are UUIDs

## Error format

All errors return a consistent structure:

```json theme={"theme":{"light":"github-light","dark":"dark-plus"}}
{
  "error": "error_code",
  "message": "Human-readable description"
}
```

## Common error codes

| Status | Code                         | Description                                                   |
| ------ | ---------------------------- | ------------------------------------------------------------- |
| 400    | `invalid_mailbox_name`       | Mailbox name doesn't meet format requirements                 |
| 400    | `missing_idempotency_key`    | Send endpoint requires Idempotency-Key header                 |
| 401    | `unauthorized`               | Invalid or missing API key                                    |
| 403    | `feature_requires_paid_plan` | Paid-only feature used on free plan (e.g. external `replyTo`) |
| 404    | `not_found`                  | Resource doesn't exist or doesn't belong to your account      |
| 409    | `address_taken`              | Mailbox name or address already in use                        |
| 422    | `recipient_suppressed`       | Recipient is on the suppression list                          |
| 429    | `rate_limit_exceeded`        | Too many requests - check `Retry-After` header                |
| 429    | `cold_outreach_limit`        | Cold send limit exceeded for new inbox                        |

## Idempotency

The `POST /v1/inboxes/:id/send` endpoint requires an `Idempotency-Key` header. If you retry a request with the same key, we return the original response without sending a duplicate email. Keys are scoped to your account and expire after 24 hours.