<!-- Canonical: https://staging.startupmail.dev/docs/api-overview -->
<!-- Documentation index: https://staging.startupmail.dev/llms.txt -->

# API overview

> Authenticate to the v1 REST API, choose capabilities, and handle responses and errors.

## Base URL

All public REST routes use HTTPS beneath:

```text
https://startupmail.dev/v1
```

The SDK uses this base by default. During local development, pass your local origin as `baseUrl`.

## OpenAPI specification

Agents and API tooling can discover the public REST API automatically from:

```text
https://startupmail.dev/openapi.json
```

The specification covers the API-key-authenticated `/v1` routes. The Streamable HTTP MCP endpoint
uses protocol-level tool discovery instead; see [MCP for agents](https://staging.startupmail.dev/docs/mcp.md).

## Create an API key

Open **Settings → Developers → API keys**. Give the key a workload-specific name, optional description and expiry, and only the capabilities it needs. The full secret is shown once.

| Capability                      | Allows                                               |
| ------------------------------- | ---------------------------------------------------- |
| `mailboxes:read`                | List accessible mailbox metadata                     |
| `mail:read`                     | List threads, read threads, and download attachments |
| `mail:send`                     | Upload attachments, send, and reply                  |
| `webhooks:write`                | List, create, and delete webhook endpoints           |
| `mailboxes:write`               | Provision mailboxes through the API                  |
| `domains:write`                 | Start domain verification                            |
| `tenants:read`, `tenants:write` | Manage isolated agent/customer tenants               |
| `drafts:read`, `drafts:write`   | Review, create, and schedule drafts                  |
| `drafts:send`                   | Approve or schedule a stored draft                   |
| `policies:write`                | Configure mailbox communication allow/block lists    |

## Authenticate

Send the key as a Bearer token. Never expose it in browser code or commit it to source control.

```bash
curl https://startupmail.dev/v1/mailboxes \
  -H "Authorization: Bearer $STARTUPMAIL_API_KEY" \
  -H "Accept: application/json"
```

## Response shape

Successful JSON resources are wrapped in `data`. Sending returns `202`; creation commonly returns `201`; a successful delete returns `204` with no body.

Errors use a stable code and a readable message:

```json
{
  "error": {
    "code": "insufficient_capability",
    "message": "This API key requires the mail:read capability."
  }
}
```

The response `x-request-id` is useful when contacting support. Clients should handle `401`, `403`, `404`, `413`, and `429` explicitly and retry only when the operation is safe to repeat.

> **Prefer one key per workload**
>
> Separate keys make rotation, expiry, last-used review, and incident containment much simpler than
> sharing one broad secret.

See [Agent inboxes](https://staging.startupmail.dev/docs/agent-inboxes.md) for provisioning, resource-scoped keys, drafts, and policies.