Send email
POST https://api.voozin.com/v1/emails sends one email to up to 50 recipients. It needs an API key with the emails:send scope and a verified sending domain. Requests and responses use snake_case JSON.
Parameters
| Field | Type | Notes |
|---|---|---|
from | string | "Name <address@your-domain>" or a bare address on a verified domain |
to | string[] | Up to 50 addresses |
cc, bcc | string[] | Optional |
reply_to | string or string[] | Where replies go |
subject | string | Required unless you send a template |
html, text | string | At least one, unless you send a template. Send both for the best deliverability |
attachments | object[] | filename plus base64 content, or an https path to download from. Up to 20 MB in total |
headers | object | Extra headers, for example {"X-Entity-Ref-ID": "order-1042"} |
tags | object | Up to 10 string values, for filtering and reporting: {"category": "receipt"} |
metadata | object | Up to 4 KB of JSON, returned in webhooks |
track_opens, track_clicks | boolean | Override the domain's tracking defaults |
unsubscribe | boolean | Adds List-Unsubscribe headers (always on for campaigns) |
scheduled_at | string | ISO 8601 time up to 30 days ahead |
template_id, template_version, variables | Send a stored template instead of subject/html/text |
Example
curl https://api.voozin.com/v1/emails \
-H "Authorization: Bearer $VOOZIN_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-1042-receipt" \
-d '{
"from": "Acme Billing <billing@acme.com>",
"to": ["ada@example.com"],
"reply_to": "support@acme.com",
"subject": "Your receipt for order #1042",
"html": "<h1>Thanks, Ada</h1><p>Your order is on its way.</p>",
"text": "Thanks, Ada. Your order is on its way.",
"attachments": [{ "filename": "receipt-1042.pdf", "path": "https://files.acme.com/receipts/1042.pdf" }],
"tags": { "category": "receipt" },
"metadata": { "order_id": 1042 }
}'import { Voozin } from "voozin";
const voozin = new Voozin(process.env.VOOZIN_API_KEY);
await voozin.emails.send(
{
from: "Acme Billing <billing@acme.com>",
to: ["ada@example.com"],
subject: "Your receipt for order #1042",
html: "<h1>Thanks, Ada</h1><p>Your order is on its way.</p>",
attachments: [{ filename: "receipt-1042.pdf", content: pdfBuffer.toString("base64") }],
metadata: { order_id: 1042 },
},
{ idempotencyKey: "order-1042-receipt" },
);The response is { "id", "status", "suppressed", "scheduled_at" }.
Idempotency
Send an Idempotency-Key header (up to 256 characters) so a network retry never sends twice. Repeating a request with the same key within 24 hours returns the first response without sending again. Reusing a key with a different body returns 422; repeating it while the first request is still running returns 409. If the first request failed, the key is released and you can retry.
Use a key that identifies the business event, such as order-1042-receipt or password-reset-<token id>.
Batch sending
POST /v1/emails/batch with { "emails": [ ... ] } sends up to 100 different emails in one request. Every entry is validated first; if any entry is invalid, nothing is sent and the error includes its index.
await voozin.emails.batch([
{ from: "hello@acme.com", to: ["a@example.com"], subject: "Hi A", text: "…" },
{ from: "hello@acme.com", to: ["b@example.com"], subject: "Hi B", text: "…" },
]);Scheduling
Set scheduled_at to send later (up to 30 days). While the email is SCHEDULED you can:
- reschedule it:
PATCH /v1/emails/:idwith{ "scheduled_at": "2026-11-02T09:00:00Z" } - cancel it:
POST /v1/emails/:id/cancel
Status and history
GET /v1/emails/:idreturns per-recipient status and events (delivered, bounced, opened, clicked and so on), and the rendered content for 7 days.GET /v1/emailslists emails, newest first. Filter withstatus,tag(nameorname:value),source(apiorcampaign),to,afterandbefore; page withlimitandcursor(pass the previous page'snext_cursor).
Both need the emails:read scope.
Suppression
Addresses that hard bounced, marked your mail as spam, or unsubscribed are suppressed for your organization. Sends to them are skipped and listed in suppressed. Admins can remove an address under Deliverability → Suppressions.
Errors
Errors are JSON: { "statusCode": 422, "error": "Unprocessable Entity", "message": "…" }.
| Status | Meaning |
|---|---|
400 | Invalid request body |
401 | Missing or invalid API key |
402 | The plan doesn't include transactional email, a trial reached its included amount, or billing lapsed and the organization is read-only |
403 | The key lacks the scope, or is restricted to another domain |
409 / 422 | Idempotency conflict (see above) |
429 | Rate limited. Wait for the Retry-After seconds |
The default rate limit is 10 requests per second per key. Responses include RateLimit-Limit and RateLimit-Remaining. The Node.js SDK retries 429 and 5xx responses automatically.