# API reference

The interactive OpenAPI reference, with every field and response schema, is at [api.voozin.com/v1/docs](https://api.voozin.com/v1/docs). The machine-readable spec is at [api.voozin.com/v1/openapi.json](https://api.voozin.com/v1/openapi.json). This page summarizes the conventions and endpoints.

## Base URL and format

```
https://api.voozin.com/v1
```

Requests and responses are JSON with `snake_case` field names. Times are ISO 8601 in UTC.

## Authentication

Create API keys in the dashboard under **Developers → API keys**. Send the key as a Bearer token:

```
Authorization: Bearer ic_live_...
```

Keys are shown once; Voozin stores only a hash. A key can be restricted to one sending domain.

## Scopes

| Scope | Grants |
| --- | --- |
| `emails:send` | `POST /v1/emails`, `/v1/emails/batch`, cancel and reschedule |
| `emails:read` | `GET /v1/emails`, `GET /v1/emails/:id` |
| `templates` | `/v1/templates` |
| `contacts` | `/v1/contacts`, `/v1/lists`, `/v1/segments`, `/v1/contact-imports` |
| `campaigns` | `/v1/campaigns`, `/v1/marketing/settings` |
| `webhooks` | `/v1/webhooks` |
| `inbound` | `/v1/inbound-routes`, `/v1/inbound` |
| `domains:read` | `GET /v1/domains`, `GET /v1/domains/:id` |

## Rate limits

10 requests per second per key by default. Responses carry `RateLimit-Limit` and `RateLimit-Remaining`; a `429` carries `Retry-After` in seconds. Use [batch sending](https://voozin.com/docs/sending#batch-sending) for bursts.

## Errors

```json
{ "statusCode": 403, "error": "Forbidden", "message": "This API key lacks the emails:send scope" }
```

`400` invalid input, `401` bad key, `402` plan or billing limit, `403` scope or domain restriction, `404` not found, `409`/`422` idempotency conflict or invalid state, `429` rate limited, `5xx` server error (safe to retry with an idempotency key).

## Pagination

List endpoints that can grow return `{ "data": [...], "next_cursor": "…" }`. Pass `cursor=<next_cursor>` and optionally `limit` for the next page; `next_cursor` is `null` on the last page.

## Idempotency

`POST /v1/emails` and `/v1/emails/batch` accept an `Idempotency-Key` header. See [Send email](https://voozin.com/docs/sending#idempotency).

## Endpoints

### Emails

| Method | Path | Description |
| --- | --- | --- |
| `POST` | `/v1/emails` | Send an email |
| `POST` | `/v1/emails/batch` | Send up to 100 emails |
| `GET` | `/v1/emails` | List emails (`status`, `tag`, `source`, `campaign_id`, `to`, `after`, `before`, `limit`, `cursor`) |
| `GET` | `/v1/emails/:id` | Get an email with per-recipient events |
| `PATCH` | `/v1/emails/:id` | Reschedule (`scheduled_at`) |
| `POST` | `/v1/emails/:id/cancel` | Cancel a scheduled email |

### Templates

| Method | Path | Description |
| --- | --- | --- |
| `GET` | `/v1/templates` | List templates |
| `POST` | `/v1/templates` | Create a template with its first version |
| `GET` | `/v1/templates/:idOrAlias` | Get a template and its versions |
| `PATCH` | `/v1/templates/:id` | Rename or change the alias |
| `DELETE` | `/v1/templates/:id` | Delete |
| `POST` | `/v1/templates/:id/versions` | Add a version |
| `POST` | `/v1/templates/:id/publish` | Publish a version |
| `POST` | `/v1/templates/:id/preview` | Render a stored version |
| `POST` | `/v1/templates/render` | Render unsaved content |

### Webhooks

| Method | Path | Description |
| --- | --- | --- |
| `GET`, `POST` | `/v1/webhooks` | List or create endpoints (`url`, `events`, `description`) |
| `GET`, `PATCH`, `DELETE` | `/v1/webhooks/:id` | Read, update or delete an endpoint |
| `GET` | `/v1/webhooks/:id/secret` | Read the signing secret |
| `POST` | `/v1/webhooks/:id/secret/rotate` | Rotate the secret |
| `POST` | `/v1/webhooks/:id/test` | Send a test event |
| `GET` | `/v1/webhooks/:id/deliveries` | Delivery log |
| `POST` | `/v1/webhooks/:id/deliveries/:deliveryId/replay` | Replay one delivery |
| `POST` | `/v1/webhooks/:id/replay` | Replay failed deliveries in a time range |

### Inbound

| Method | Path | Description |
| --- | --- | --- |
| `GET`, `POST` | `/v1/inbound-routes` | List or create routes (`domain_id`, `pattern`, `endpoint_id`, `mailbox_id`) |
| `GET`, `PATCH`, `DELETE` | `/v1/inbound-routes/:id` | Read, update or delete a route |
| `GET` | `/v1/inbound` | Received messages (`route_id`, `status`, `limit`, `cursor`) |
| `GET` | `/v1/inbound/:id` | Payload and webhook attempts |
| `GET` | `/v1/inbound/:id/raw` | The original message (`message/rfc822`) |
| `GET` | `/v1/inbound/:id/attachments/:index` | One attachment |
| `POST` | `/v1/inbound/:id/replay` | Send `inbound.received` again |

### Domains

| Method | Path | Description |
| --- | --- | --- |
| `GET` | `/v1/domains` | List domains and their status |
| `GET` | `/v1/domains/:id` | A domain with its DNS records |

### Marketing

Contacts, lists, segments, imports and campaigns are under `/v1/contacts`, `/v1/lists`, `/v1/segments`, `/v1/contact-imports`, `/v1/campaigns` and `/v1/marketing/settings`. See the [OpenAPI reference](https://api.voozin.com/v1/docs) for their fields.
