# 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](https://voozin.com/docs/templates) instead of `subject`/`html`/`text` |

## Example

```bash
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 }
  }'
```

```ts
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`.

```ts
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": "…" }`.

| 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.
