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

ScopeGrants
emails:sendPOST /v1/emails, /v1/emails/batch, cancel and reschedule
emails:readGET /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:readGET /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

MethodPathDescription
POST/v1/emailsSend an email
POST/v1/emails/batchSend up to 100 emails
GET/v1/emailsList emails (status, tag, source, campaign_id, to, after, before, limit, cursor)
GET/v1/emails/:idGet an email with per-recipient events
PATCH/v1/emails/:idReschedule (scheduled_at)
POST/v1/emails/:id/cancelCancel a scheduled email

Templates

MethodPathDescription
GET/v1/templatesList templates
POST/v1/templatesCreate a template with its first version
GET/v1/templates/:idOrAliasGet a template and its versions
PATCH/v1/templates/:idRename or change the alias
DELETE/v1/templates/:idDelete
POST/v1/templates/:id/versionsAdd a version
POST/v1/templates/:id/publishPublish a version
POST/v1/templates/:id/previewRender a stored version
POST/v1/templates/renderRender unsaved content

Webhooks

MethodPathDescription
GET, POST/v1/webhooksList or create endpoints (url, events, description)
GET, PATCH, DELETE/v1/webhooks/:idRead, update or delete an endpoint
GET/v1/webhooks/:id/secretRead the signing secret
POST/v1/webhooks/:id/secret/rotateRotate the secret
POST/v1/webhooks/:id/testSend a test event
GET/v1/webhooks/:id/deliveriesDelivery log
POST/v1/webhooks/:id/deliveries/:deliveryId/replayReplay one delivery
POST/v1/webhooks/:id/replayReplay failed deliveries in a time range

Inbound

MethodPathDescription
GET, POST/v1/inbound-routesList or create routes (domain_id, pattern, endpoint_id, mailbox_id)
GET, PATCH, DELETE/v1/inbound-routes/:idRead, update or delete a route
GET/v1/inboundReceived messages (route_id, status, limit, cursor)
GET/v1/inbound/:idPayload and webhook attempts
GET/v1/inbound/:id/rawThe original message (message/rfc822)
GET/v1/inbound/:id/attachments/:indexOne attachment
POST/v1/inbound/:id/replaySend inbound.received again

Domains

MethodPathDescription
GET/v1/domainsList domains and their status
GET/v1/domains/:idA 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.