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

FieldTypeNotes
fromstring"Name <address@your-domain>" or a bare address on a verified domain
tostring[]Up to 50 addresses
cc, bccstring[]Optional
reply_tostring or string[]Where replies go
subjectstringRequired unless you send a template
html, textstringAt least one, unless you send a template. Send both for the best deliverability
attachmentsobject[]filename plus base64 content, or an https path to download from. Up to 20 MB in total
headersobjectExtra headers, for example {"X-Entity-Ref-ID": "order-1042"}
tagsobjectUp to 10 string values, for filtering and reporting: {"category": "receipt"}
metadataobjectUp to 4 KB of JSON, returned in webhooks
track_opens, track_clicksbooleanOverride the domain's tracking defaults
unsubscribebooleanAdds List-Unsubscribe headers (always on for campaigns)
scheduled_atstringISO 8601 time up to 30 days ahead
template_id, template_version, variablesSend 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/:id with { "scheduled_at": "2026-11-02T09:00:00Z" }
  • cancel it: POST /v1/emails/:id/cancel

Status and history

  • GET /v1/emails/:id returns per-recipient status and events (delivered, bounced, opened, clicked and so on), and the rendered content for 7 days.
  • GET /v1/emails lists emails, newest first. Filter with status, tag (name or name:value), source (api or campaign), to, after and before; page with limit and cursor (pass the previous page's next_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": "…" }.

StatusMeaning
400Invalid request body
401Missing or invalid API key
402The plan doesn't include transactional email, a trial reached its included amount, or billing lapsed and the organization is read-only
403The key lacks the scope, or is restricted to another domain
409 / 422Idempotency conflict (see above)
429Rate 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.