> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gork.email/llms.txt
> Use this file to discover all available pages before exploring further.

# API Introduction

> Base URL, authentication, envelopes, idempotency, and rate limits for the gork.email REST API.

All gork.email endpoints live under a single versioned base URL:

```bash cURL theme={null}
https://api.gork.email
```

Every public endpoint is namespaced under `/v1` (e.g. `POST /v1/messages/send`). The `/v1` prefix is immutable — backwards-compatible changes never break existing integrations.

## Authentication

Authenticate with a bearer API key on every request:

```bash cURL theme={null}
curl https://api.gork.email/v1/inboxes \
  -H "Authorization: Bearer gork_live_YOUR_API_KEY"
```

Keys are formatted as `gork_live_...` (production) or `gork_test_...` (test). Only the SHA-256 hash is stored server-side — the raw key is shown exactly once at creation and can never be retrieved again.

<Warning>
  A missing or malformed `Authorization` header returns `401 unauthorized`. A revoked or unknown key returns `401 invalid_api_key`. A key whose format does not start with `gork_` returns `401 invalid_api_key_format`.
</Warning>

### Scopes

Every key carries a set of scopes. Endpoints declare the scope they require, and a key without it receives `403 insufficient_scope`. A key with the `*` wildcard scope (the default for unbound keys) may call everything.

| Scope                | Grants access to                                           |
| -------------------- | ---------------------------------------------------------- |
| `inboxes:read`       | List and fetch inboxes                                     |
| `inboxes:write`      | Provision and deactivate inboxes                           |
| `messages:read`      | List, search, and fetch messages; read attachments         |
| `messages:send`      | Send, schedule, delete, and cancel messages; manage drafts |
| `threads:read`       | List and fetch conversation threads                        |
| `webhooks:read`      | List webhooks and delivery logs                            |
| `webhooks:write`     | Register, rotate, and delete webhooks                      |
| `keys:read`          | List API keys (prefixes only, never hashes)                |
| `keys:write`         | Create and revoke API keys                                 |
| `domains:read`       | List custom domains                                        |
| `domains:write`      | Register, verify, and delete custom domains                |
| `organization:read`  | Read organization profile and member list                  |
| `suppressions:read`  | List suppressed recipients                                 |
| `suppressions:write` | Add and remove suppressions                                |

Resource wildcards are also honored: `messages:*` covers both `messages:read` and `messages:send`.

<Note>
  Inbox-bound agent keys (created with an `inboxId`) may only hold mail scopes — `inboxes:read`, `messages:read`, `messages:send`, `threads:read` — and every call is confined to their own inbox. See [API Keys](/api-reference/keys/overview).
</Note>

## Success envelope

Every successful response wraps its payload in a `data` envelope:

```json 200 OK theme={null}
{
  "data": {
    "id": "inb_728af980b4e",
    "address": "support@try.gork.email"
  }
}
```

List endpoints return an array under `data`:

```json 200 OK theme={null}
{
  "data": []
}
```

## Error envelope

Errors always use the same shape:

```json 422 Unprocessable Entity theme={null}
{
  "error": {
    "code": "recipient_suppressed",
    "message": "Cannot send email. Recipient ... is suppressed (bounce).",
    "details": {}
  }
}
```

| Field           | Always present? | Meaning                                                                                                         |
| --------------- | --------------- | --------------------------------------------------------------------------------------------------------------- |
| `error.code`    | Yes             | Stable machine-readable code (e.g. `inbox_not_found`, `validation_failed`). Branch on this, not on the message. |
| `error.message` | Yes             | Human-readable explanation.                                                                                     |
| `error.details` | No              | Extra context (validation breakdowns, suppression reason, quota diagnostics).                                   |

## Idempotency

`POST /v1/messages/send` accepts an `Idempotency-Key` header. Replaying a request with the same key returns the original result instead of sending twice:

```bash cURL theme={null}
curl -X POST https://api.gork.email/v1/messages/send \
  -H "Authorization: Bearer gork_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{ "inboxId": "inb_728af980b4e", "to": ["prospect@acmecorp.com"], "subject": "Hi" }'
```

* Keys are capped at **255 characters** — longer values are rejected with `400 validation_failed`.
* A replayed delivery returns **HTTP 200** (not 201) with an `Idempotent-Replayed: true` response header.
* Always generate a fresh UUID per logical send, and reuse it only when retrying that same send after a network failure.

## Rate limits

Requests are limited to **240 requests per minute per organization**. Every authenticated response carries the current budget:

| Header                  | Meaning                                |
| ----------------------- | -------------------------------------- |
| `X-RateLimit-Limit`     | The window allowance (`240`).          |
| `X-RateLimit-Remaining` | Requests left in the current window.   |
| `X-RateLimit-Reset`     | Unix timestamp when the window resets. |

Exceeding the budget returns `429 rate_limit_exceeded`. Back off and retry after the reset time.

## Health and machine-readable spec

* `GET https://api.gork.email/health` returns `{ "status": "healthy", "service": "gork.email", ... }` with no authentication. Use it for uptime checks.
* `GET https://api.gork.email/openapi.json` serves the full OpenAPI specification — the same source SDKs and agent tool definitions are generated from.