# API reference

Base URL `https://api-staging.avelto.dev`. Authenticate with `Authorization: Bearer <api key>`; `av_test_` keys run the pipeline without delivering. Errors are `{ "error": { "code", "message" } }`. The full machine-readable spec is at https://staging.avelto.dev/openapi.json (YAML: https://staging.avelto.dev/openapi.yaml).

| Method | Path | Summary |
| --- | --- | --- |
| `POST` | `/v1/emails` | Send an email. Queues an email. Returns 201 with the id, or 200 with the existing id when the Idempotency-Key was seen before. Sandbox senders only deliver to the account owner or the simulator addresses; other senders must be a verified domain. See https://staging.avelto.dev/docs/send-email. |
| `GET` | `/v1/emails` | List emails. Newest first, cursor-paginated. mode defaults to the API key's mode. |
| `GET` | `/v1/emails/{id}` | Get an email with its events |
| `POST` | `/v1/emails/{id}/cancel` | Cancel a scheduled email |
| `POST` | `/v1/emails/batch` | Send up to 100 emails. Each message is validated, limited and queued exactly as a single send is; results[i] lines up with messages[i]. 200 when every message was accepted, 422 when none was, 207 when mixed. See https://staging.avelto.dev/docs/send-email. |
| `POST` | `/v1/templates` | Create a template. A reusable subject and body with {{variables}} in them. Needs the templates:manage scope. See https://staging.avelto.dev/docs/templates. |
| `GET` | `/v1/templates` | List templates |
| `GET` | `/v1/templates/{id}` | Get a template |
| `PATCH` | `/v1/templates/{id}` | Update a template. Only the fields you pass change. null clears a body part. Every save keeps a version. |
| `DELETE` | `/v1/templates/{id}` | Delete a template. Emails already sent keep the text they were sent with. |
| `GET` | `/v1/templates/{id}/versions` | List versions. Newest first. Every save is kept. |
| `POST` | `/v1/templates/{id}/restore` | Restore a version. Writes the old version forward as a new one, so the history stays append-only. |
| `POST` | `/v1/domains` | Add a sending domain. Returns the DNS records to publish. Poll GET /v1/domains/{id} until status is verified. |
| `GET` | `/v1/domains` | List domains |
| `GET` | `/v1/domains/{id}` | Get a domain (re-checks verification) |
| `DELETE` | `/v1/domains/{id}` | Delete a domain. Needs a live key: a test key gets 403 forbidden. |
| `GET` | `/v1/suppressions` | List suppressed addresses |
| `POST` | `/v1/suppressions` | Suppress an address manually |
| `DELETE` | `/v1/suppressions/{email}` | Remove an address from the suppression list |
| `POST` | `/v1/webhooks` | Create a webhook endpoint. The signing secret is returned once. Endpoint URLs must be https in production and may not point at private networks. Events: https://staging.avelto.dev/docs/webhooks/events. |
| `GET` | `/v1/webhooks` | List webhook endpoints |
| `GET` | `/v1/webhooks/{id}` | Get a webhook endpoint |
| `DELETE` | `/v1/webhooks/{id}` | Delete a webhook endpoint |
| `GET` | `/v1/webhooks/{id}/deliveries` | List deliveries for an endpoint |
| `POST` | `/v1/webhooks/{id}/deliveries/{deliveryId}/retry` | Retry a delivery. Re-enqueues the existing delivery. Its attempt count keeps climbing; no new delivery is created. |
| `GET` | `/v1/account` | Describe the account and what is set up. The key's mode and scopes, the sandbox domain with every address a sandbox send may reach, and the account's domains, webhook endpoints and templates. Read this first when integrating: it says what exists and what the next step is. |
| `GET` | `/v1/account/export` | Export everything held for the account. One JSON document: account, users, keys, domains, emails with bodies, events, suppressions and webhooks. Answers a data subject access request. Needs a live key and the account:manage scope. |
| `POST` | `/v1/recipients/erase` | Erase a recipient. Removes the address from emails, events and stored bodies, keeping only a hashed suppression entry so the address is never sent to again. Needs a live key and the account:manage scope. |

---

Rendered page: https://staging.avelto.dev/docs/api