API reference
The interactive OpenAPI reference, with every field and response schema, is at api.voozin.com/v1/docs. The machine-readable spec is at 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 for bursts.
Errors
{ "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.
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 for their fields.