# Voozin > Voozin is an email platform for businesses and developers: end-to-end encrypted business email (webmail, IMAP/SMTP, calendars) on unlimited custom domains, a transactional email REST API, marketing campaigns, and inbound email that is parsed and delivered to your webhook so apps can receive and reply to mail. Voozin is operated by Neurochain Limited (UK company 14894776). Support: support@voozin.com. ## Key facts - Business email: $4 per user / month, 14-day free trial, no card required. - Transactional email REST API at https://api.voozin.com/v1 with Bearer API keys (ic_live_...), idempotency keys, batch sending, scheduling, templates and signed delivery webhooks (Standard Webhooks). - SMTP submission on ports 465 (TLS) and 587 (STARTTLS): apps and mail clients sign in as a mailbox with an app password and send as that mailbox. App email at volume should use the REST API. - Mail and calendar apps: IMAP (imap.inboxcluster.net:993), SMTP and CalDAV (https://mail.voozin.com/dav/) with app passwords; automatic setup through Thunderbird autoconfig, Outlook autodiscover and an Apple configuration profile. - Sign in with Voozin: OAuth 2.1 and OpenID Connect provider with issuer https://auth.voozin.com (PKCE required; scopes openid, profile, email, offline_access, mail, calendar). Access tokens with the mail or calendar scope sign in to IMAP and SMTP (XOAUTH2, OAUTHBEARER) and CalDAV (Bearer). - Inbound routes: mail to an address or pattern on your domain is parsed (headers, text, HTML, attachments) and POSTed to your webhook; replies thread with In-Reply-To and References. - Node.js SDK: npm install voozin. WordPress plugin: "Voozin" (replaces wp_mail and adds an inbox for inbound mail). - Deliverability: DKIM (RSA and Ed25519), SPF, DMARC, MTA-STS, TLS reporting, blocklist monitoring, shared or dedicated IPs. - Security: OpenPGP end-to-end encryption, keys unlocked only in the browser, two-factor authentication and passkeys. - Data controller and processor terms under UK GDPR and EU GDPR; company based in London, United Kingdom. ## Pricing add-ons - Extra storage: $3 per 10 GB / month. Grow the organization pool. Admins decide how it is split with per-mailbox caps. - Dedicated IP: $30 per IP / month. Your own sending IP with reverse DNS, managed warm-up and reputation monitoring. - Additional domain IP: $20 per IP / month. Isolate a second brand or domain on its own IP so reputations never mix. - Transactional email: $10 per month, 50k emails included, then $0.80 per 1,000 emails. API and SMTP relay for receipts, password resets and alerts, with delivery webhooks. - Marketing email: $25 per month, 10k contacts included, then $2 per 1,000 contacts. Campaigns, audiences and one-click unsubscribe that meets Gmail and Yahoo sender rules. - Inbound routes: $15 per route / month. Receive mail for an address or pattern like support@ and get it parsed and signed at your webhook, with attachments and replay. --- # Quickstart Send your first email through the Voozin API in about five minutes. You need a Voozin account ([start a free trial](https://app.voozin.com/sign-up), no card required) and access to your domain's DNS. ## 1. Verify a sending domain In the dashboard open **Domains → Add domain** and enter the domain you want to send from, for example `acme.com`. Voozin shows the DNS records to publish (SPF, DKIM, DMARC, MTA-STS and an MX if you also want to receive mail). The setup wizard has step-by-step guides for Cloudflare, GoDaddy, Name.com, Namecheap, Amazon Route 53 and DigitalOcean. When the records resolve, the domain turns **Active**. See [Domains and DNS](https://voozin.com/docs/domains) for details. ## 2. Create an API key Open **Developers → API keys → Create key**, give it a name and the `emails:send` scope. The key (`ic_live_…`) is shown once. Store it as an environment variable: ```bash export VOOZIN_API_KEY="ic_live_..." ``` Keep keys on the server. Never put them in browser code or a mobile app. ## 3. Send an email With curl: ```bash curl https://api.voozin.com/v1/emails \ -H "Authorization: Bearer $VOOZIN_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "from": "Acme ", "to": ["ada@example.com"], "subject": "Welcome to Acme", "html": "

Thanks for signing up!

", "text": "Thanks for signing up!" }' ``` With the [Node.js SDK](https://voozin.com/docs/sdk/node): ```bash npm install voozin ``` ```ts import { Voozin } from "voozin"; const voozin = new Voozin(process.env.VOOZIN_API_KEY); const email = await voozin.emails.send({ from: "Acme ", to: ["ada@example.com"], subject: "Welcome to Acme", html: "

Thanks for signing up!

", }); console.log(email.id, email.status); ``` The response looks like this: ```json { "id": "6f1c0e7a-…", "status": "QUEUED", "suppressed": [], "scheduled_at": null } ``` Recipients who previously hard bounced, complained or unsubscribed are listed in `suppressed` and are not sent to. ## 4. Track delivery Look the email up with `GET /v1/emails/:id` (scope `emails:read`), or better, receive events as they happen with a [webhook](https://voozin.com/docs/webhooks): `email.delivered`, `email.bounced`, `email.opened` and more. ## Next steps - [Send email](https://voozin.com/docs/sending): attachments, tags, scheduling, batch sending and idempotency. - [Templates](https://voozin.com/docs/templates): keep email content out of your code. - [Inbound email](https://voozin.com/docs/inbound): receive mail at `support@yourdomain.com` in your app. - [WordPress plugin](https://voozin.com/docs/wordpress): send all WordPress mail through Voozin without code. Source: https://voozin.com/docs/quickstart --- # Domains and DNS Voozin sends only from domains you have verified. Verification publishes the records that prove you own the domain and let receiving servers trust your mail. ## Add a domain In the dashboard open **Domains → Add domain**. One domain can be used for business mailboxes, API sending, campaigns and inbound routes at the same time. There is no limit on the number of domains. ## Records to publish The domain page lists the exact values for your domain. They typically include: | Record | Purpose | | --- | --- | | `TXT @` with `v=spf1 … ~all` | SPF: authorizes Voozin's servers to send for the domain | | `TXT ._domainkey` (RSA and Ed25519) | DKIM: signs every message so it cannot be altered | | `TXT _dmarc` | DMARC: tells receivers what to do with mail that fails SPF and DKIM, and where to send reports | | `MX @` | Receives mail for mailboxes and inbound routes | | `TXT _mta-sts` and `CNAME mta-sts` | MTA-STS: requires TLS when other servers deliver mail to you | | `TXT _smtp._tls` | TLS reporting | If you already send mail from the domain with another provider, merge SPF into a single `TXT` record (`v=spf1 include:… include:… ~all`). A domain must have only one SPF record. The **Export** button on the domain page downloads the records as a BIND zone file or CSV, which most DNS providers can import. ## Verification Voozin checks the records automatically. Once the required records resolve, the domain becomes **Active** (`status: "ACTIVE"`) and you can send. Click **Verify DNS** to check immediately after a change; DNS changes can take up to an hour to propagate, depending on the record's TTL. ## Domains over the API An API key with the `domains:read` scope can list domains and their DNS status. This is how plugins such as [WordPress](https://voozin.com/docs/wordpress) offer a list of verified sender domains. ```bash curl https://api.voozin.com/v1/domains -H "Authorization: Bearer $VOOZIN_API_KEY" ``` ```json { "data": [ { "id": "d3c1…", "name": "acme.com", "status": "ACTIVE", "verified_at": "2026-10-01T09:12:44.000Z", "track_opens": false, "track_clicks": false, "created_at": "2026-10-01T09:02:10.000Z" } ] } ``` `GET /v1/domains/:id` adds `dns_records` with each record's `type`, `purpose`, `host`, `value`, `priority` and `status`. ## Restricting a key to one domain When you create an API key you can restrict it to one domain. That key can then only send from addresses on that domain, which limits the damage if a key for one site leaks. ## Deliverability tips - Send marketing from a subdomain (for example `news.acme.com`) so its reputation is separate from your transactional mail. - Keep DMARC at `p=none` while you check reports, then move to `quarantine` or `reject`. - A [dedicated IP](https://voozin.com/pricing) only helps with consistent volume. Most senders do better on the shared, monitored pool. Source: https://voozin.com/docs/domains --- # 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 "` 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 ", "to": ["ada@example.com"], "reply_to": "support@acme.com", "subject": "Your receipt for order #1042", "html": "

Thanks, Ada

Your order is on its way.

", "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 ", to: ["ada@example.com"], subject: "Your receipt for order #1042", html: "

Thanks, Ada

Your order is on its way.

", 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-`. ## 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. Source: https://voozin.com/docs/sending --- # Templates Templates keep email content out of your code. Designers can edit them in the dashboard while your app sends them by a stable alias. Every edit creates a new version, and sends use the published version. ## Syntax Templates use Jinja syntax: ```html

Hi {{ first_name }},

{% if items %}
    {% for item in items %}
  • {{ item.name }}: {{ item.price }}
  • {% endfor %}
{% endif %} ``` Variables in HTML are escaped automatically, so user input cannot inject markup. The subject and text body are templates too. ## Create a template In the dashboard open **Developers → Templates**, or use the API (scope `templates`): ```bash curl https://api.voozin.com/v1/templates \ -H "Authorization: Bearer $VOOZIN_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Password reset", "alias": "password-reset", "subject": "Reset your {{ product }} password", "html": "

Hi {{ first_name }}, reset your password.

", "text": "Hi {{ first_name }}, reset your password: {{ reset_url }}", "sample_data": { "first_name": "Ada", "product": "Acme", "reset_url": "https://acme.com/reset/abc" }, "publish": true }' ``` An alias may contain lowercase letters, digits, `_` and `-`. ## Send a template Pass `template_id` (the id or the alias) and `variables` instead of `subject`, `html` and `text`: ```ts await voozin.emails.send({ from: "Acme ", to: [user.email], template_id: "password-reset", variables: { first_name: user.firstName, product: "Acme", reset_url: url }, }); ``` Add `template_version` to send a specific version instead of the published one. ## Versions - `POST /v1/templates/:id/versions` adds a version with new content. - `POST /v1/templates/:id/publish` with `{ "version": 3 }` makes it the one that sends. - `GET /v1/templates/:id` returns the template and its versions. ## Preview - `POST /v1/templates/:id/preview` with optional `version` and `variables` renders a stored template (it defaults to the version's sample data). - `POST /v1/templates/render` with `subject`, `html`, `text` and `variables` renders content without saving it, useful for an editor preview. ```ts const preview = await voozin.templates.render({ subject: "Hello {{ name }}", html: "

Hello {{ name }}

", variables: { name: "Ada" }, }); ``` ## List templates `GET /v1/templates` returns `data` with each template's `id`, `name`, `alias`, `published_version`, `latest_version` and `subject`. Source: https://voozin.com/docs/templates --- # SMTP Any application that can send mail over SMTP can send through Voozin: CMSs, helpdesks, printers, cron jobs and mail clients. SMTP sends from a mailbox, so the sender address is the mailbox you sign in with. For high-volume app email, prefer the [REST API](https://voozin.com/docs/sending), which adds templates, idempotency, tags and delivery webhooks. ## Settings | Setting | Value | | --- | --- | | Host | `smtp.inboxcluster.net` (the **Connect** dialog shows the host for your account) | | Port | `465` with SSL/TLS, or `587` with STARTTLS | | Authentication | Normal password (`PLAIN` or `LOGIN`) | | User name | The full mailbox address, for example `no-reply@acme.com` | | Password | An app password for that mailbox | Connections without TLS are refused. ## Create a sending mailbox and app password 1. In the dashboard open **Mailboxes** and create a mailbox for the application, for example `no-reply@acme.com`. A **standard** encryption mode mailbox is the simplest choice for application mail. 2. Click **Connect** next to the mailbox and create an app password. It is shown once. 3. Enter the settings above in your application. Revoke the app password from the same dialog if it leaks. Repeated wrong passwords temporarily block the client's IP address. ## Rules - The `MAIL FROM` address must be the authenticated mailbox. To send as several addresses, create a mailbox for each. - Each mailbox and organization has an hourly recipient limit, and suppressed addresses (hard bounces, complaints) are refused. - Sent messages are stored in the mailbox's Sent folder. ## Examples Node.js with Nodemailer: ```ts import nodemailer from "nodemailer"; const transport = nodemailer.createTransport({ host: "smtp.inboxcluster.net", port: 465, secure: true, auth: { user: "no-reply@acme.com", pass: process.env.VOOZIN_SMTP_PASSWORD }, }); await transport.sendMail({ from: "Acme ", to: "ada@example.com", subject: "Hello", text: "Hi Ada" }); ``` PHP with PHPMailer: ```php $mail = new PHPMailer\PHPMailer\PHPMailer(true); $mail->isSMTP(); $mail->Host = 'smtp.inboxcluster.net'; $mail->Port = 587; $mail->SMTPSecure = PHPMailer\PHPMailer\PHPMailer::ENCRYPTION_STARTTLS; $mail->SMTPAuth = true; $mail->Username = 'no-reply@acme.com'; $mail->Password = getenv('VOOZIN_SMTP_PASSWORD'); $mail->setFrom('no-reply@acme.com', 'Acme'); $mail->addAddress('ada@example.com'); $mail->Subject = 'Hello'; $mail->Body = 'Hi Ada'; $mail->send(); ``` For WordPress, use the [Voozin plugin](https://voozin.com/docs/wordpress) instead of an SMTP plugin: it sends over the API and adds a delivery log and inbound mail. Source: https://voozin.com/docs/smtp --- # Webhooks Webhooks push events to your server as they happen: deliveries, bounces, opens, clicks, unsubscribes and inbound mail. Every request is signed with the [Standard Webhooks](https://www.standardwebhooks.com/) scheme so you can prove it came from Voozin. ## Add an endpoint In the dashboard open **Developers → Webhooks → Add endpoint**, or call the API with a key that has the `webhooks` scope: ```bash curl https://api.voozin.com/v1/webhooks \ -H "Authorization: Bearer $VOOZIN_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://acme.com/api/webhooks/voozin", "events": ["email.delivered", "email.bounced", "inbound.received"] }' ``` The response includes the signing `secret` (`whsec_…`). Store it as `VOOZIN_WEBHOOK_SECRET`. An empty `events` list subscribes to every event type, including future ones. Endpoints must be public `https` URLs. Private and loopback addresses are refused. ## Event types | Event | When | | --- | --- | | `email.sent` | Accepted by Voozin and handed to the queue | | `email.scheduled`, `email.canceled` | A scheduled email was created or canceled | | `email.delivered` | The receiving server accepted the message | | `email.delivery_delayed` | A temporary failure; Voozin keeps retrying | | `email.bounced` | A permanent failure. The address is suppressed | | `email.complained` | The recipient marked the message as spam | | `email.opened`, `email.clicked` | Tracking events, when tracking is on | | `email.unsubscribed` | The recipient used the unsubscribe link | | `contact.created`, `contact.updated`, `contact.unsubscribed` | Marketing contact changes | | `inbound.received` | Mail arrived for an [inbound route](https://voozin.com/docs/inbound) | ## Payload Each delivery is a `POST` with a JSON body: ```json { "type": "email.delivered", "timestamp": "2026-10-26T10:04:12.511Z", "data": { "email_id": "6f1c0e7a-2d4b-4c1e-9a51-0b7f3c2e8d10", "from": "Acme Billing ", "to": ["ada@example.com"], "recipient": "ada@example.com", "subject": "Your receipt for order #1042", "tags": { "category": "receipt" }, "metadata": { "order_id": 1042 }, "campaign_id": null, "contact_id": null, "created_at": "2026-10-26T10:04:10+00:00" } } ``` Email events are sent per recipient (`recipient`) and include the `tags` and `metadata` you sent, so you can link an event to your own records. Some events add details, such as the bounce reason. Message-level events (`email.sent`, `email.scheduled`, `email.canceled`) have no `recipient`. Email events cover mail sent through the API and campaigns; mail sent from mailboxes (webmail, SMTP) does not produce webhooks. ## Verify the signature Each request carries three headers: - `webhook-id`: the message id. It stays the same across retries, so use it to ignore duplicates. - `webhook-timestamp`: Unix seconds. Reject requests older than five minutes. - `webhook-signature`: one or more space-separated `v1,` signatures, an HMAC-SHA256 of `{webhook-id}.{webhook-timestamp}.{raw body}` keyed with the base64-decoded part of the secret after `whsec_`. Always verify against the **raw** request body, before parsing JSON. With the Node.js SDK: ```ts import { verifyWebhook } from "voozin"; const event = await verifyWebhook(rawBody, request.headers, process.env.VOOZIN_WEBHOOK_SECRET!); // throws WebhookVerificationError when the signature or timestamp is wrong ``` Without the SDK, in Node.js: ```js import crypto from "node:crypto"; export function verifyWebhook(secret, headers, rawBody) { const id = headers["webhook-id"]; const timestamp = headers["webhook-timestamp"]; if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false; const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64"); const expected = crypto.createHmac("sha256", key).update(`${id}.${timestamp}.${rawBody}`).digest("base64"); return headers["webhook-signature"].split(" ").some((sig) => { const [, value] = sig.split(","); return value && value.length === expected.length && crypto.timingSafeEqual(Buffer.from(value), Buffer.from(expected)); }); } ``` In Python: ```python import base64, hashlib, hmac, time def verify_webhook(secret: str, headers: dict, raw_body: bytes) -> bool: msg_id, ts = headers["webhook-id"], headers["webhook-timestamp"] if abs(time.time() - int(ts)) > 300: return False key = base64.b64decode(secret.removeprefix("whsec_")) expected = base64.b64encode(hmac.new(key, f"{msg_id}.{ts}.".encode() + raw_body, hashlib.sha256).digest()).decode() return any(hmac.compare_digest(sig.split(",", 1)[-1], expected) for sig in headers["webhook-signature"].split()) ``` In PHP: ```php function voozin_verify_webhook(string $secret, array $headers, string $rawBody): bool { $id = $headers['webhook-id'] ?? ''; $ts = $headers['webhook-timestamp'] ?? ''; if (abs(time() - (int) $ts) > 300) return false; $key = base64_decode(preg_replace('/^whsec_/', '', $secret)); $expected = base64_encode(hash_hmac('sha256', "$id.$ts.$rawBody", $key, true)); foreach (explode(' ', $headers['webhook-signature'] ?? '') as $sig) { $parts = explode(',', $sig, 2); if (isset($parts[1]) && hash_equals($expected, $parts[1])) return true; } return false; } ``` The official [Standard Webhooks libraries](https://github.com/standard-webhooks/standard-webhooks) work too. ## Retries Any `2xx` response within 10 seconds counts as delivered. Respond quickly and do slow work in a background job. Failed deliveries are retried after 1 minute, 5 minutes, 30 minutes, 1 hour, 3 hours, 6 hours and 12 hours. An endpoint that keeps failing for 5 days is disabled and the organization's admins are emailed; enabling it again clears the failure state. ## Logs and replays The dashboard shows every delivery with the request, the response and the timing. You can replay one delivery, or every failed delivery in a time range after an outage. Over the API: `GET /v1/webhooks/:id/deliveries`, `POST /v1/webhooks/:id/deliveries/:deliveryId/replay` and `POST /v1/webhooks/:id/replay`. `POST /v1/webhooks/:id/test` sends a test event. `POST /v1/webhooks/:id/secret/rotate` issues a new secret. Source: https://voozin.com/docs/webhooks --- # Inbound email Inbound routes let your application receive email. Mail sent to an address on your domain, such as `support@acme.com` or `reply+ticket-123@acme.com`, is parsed and posted to your webhook as JSON: sender, recipients, subject, text and HTML bodies, attachments and authentication results. Typical uses are support inboxes, reply-by-email for comments or tickets, receiving invoices, and turning email into tasks. Inbound routes are a paid add-on, and one route is included in the free trial. ## How it works 1. Your domain's `MX` record points to Voozin (see [Domains and DNS](https://voozin.com/docs/domains)). 2. A route matches the recipient address. 3. Voozin checks SPF, DKIM and DMARC, stores the message, and sends an `inbound.received` [webhook](https://voozin.com/docs/webhooks) to the route's endpoint. 4. Your app handles the event and can [reply](https://voozin.com/docs/inbound/replying) through the sending API. Addresses that are real mailboxes never match a route, so one domain can hold both your team's mailboxes and app addresses. ## Create a route In the dashboard open **Developers → Inbound**, or use the API with a key that has the `inbound` scope: ```bash curl https://api.voozin.com/v1/inbound-routes \ -H "Authorization: Bearer $VOOZIN_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "domain_id": "d3c1…", "pattern": "support", "endpoint_id": "5d0b8e3a-…" }' ``` ```ts await voozin.inbound.routes.create({ domain_id: domain.id, pattern: "support", endpoint_id: endpoint.id }); ``` - `pattern` is an exact local part (`support`), a prefix ending in `*` (`reply+*`), or `*` for every other address. Exact patterns win over prefixes (the longest first), and prefixes win over `*`. - `endpoint_id` is a webhook endpoint subscribed to `inbound.received` (or to all events). - `mailbox_id` additionally delivers a copy to a mailbox, so your team sees the mail in the webmail too. ## The inbound.received event ```json { "type": "inbound.received", "timestamp": "2026-10-26T10:15:03.120Z", "data": { "id": "8a4f2c1e-…", "route_id": "1c9e7b52-…", "received_at": "2026-10-26T10:15:02+00:00", "mail_from": "ada@example.com", "recipients": ["support@acme.com"], "size": 18234, "auth": { "spf": "pass", "dkimPass": true, "aligned": true, "dmarc": { "dkim": "pass", "spf": "pass", "policy": "Reject", "failed": false } }, "content_available": true, "from": { "name": "Ada Lovelace", "address": "ada@example.com" }, "to": [{ "name": null, "address": "support@acme.com" }], "cc": [], "reply_to": [], "subject": "Order #1042 hasn't arrived", "message_id": "CAF7x…@mail.gmail.com", "in_reply_to": null, "references": null, "date": "2026-10-26T10:14:58+00:00", "text": "Hi, my order hasn't arrived yet…", "html": "
Hi, my order hasn't arrived yet…
", "truncated": false, "headers": [{ "name": "X-Mailer", "value": "…" }], "attachments": [ { "index": 0, "filename": "photo.jpg", "content_type": "image/jpeg", "content_id": null, "size": 120334, "url": "https://api.voozin.com/v1/inbound/8a4f2c1e-…/attachments/0?expires=…&signature=…" } ], "raw_url": "https://api.voozin.com/v1/inbound/8a4f2c1e-…/raw?expires=…&signature=…" } } ``` - `text` and `html` are limited to 512 KB each; `truncated` is `true` when either was cut. The full message is always available from `raw_url`. - `auth` holds the SPF, DKIM and DMARC verdicts. Treat mail that is not `aligned` with care before acting on it. - Attachment `url` and `raw_url` are signed links that work without an API key for 24 hours. ## Download attachments and the raw message After 24 hours, or from your backend at any time, use a key with the `inbound` scope: ```ts const raw = await voozin.inbound.raw(event.data.id); // ArrayBuffer, message/rfc822 const file = await voozin.inbound.attachment(event.data.id, 0); // { content, contentType, filename } ``` The REST paths are `GET /v1/inbound/:id/raw` and `GET /v1/inbound/:id/attachments/:index`. ## History and replays - `GET /v1/inbound` lists received messages with their delivery status (filter by `route_id` and `status`). - `GET /v1/inbound/:id` returns the payload and the webhook attempts. - `POST /v1/inbound/:id/replay` sends the event again with fresh links, optionally to another `endpoint_id`. This is useful while developing your handler. ## Retention and encryption Inbound message content is stored encrypted for 7 days, then deleted; only the envelope remains. Routed mail is decrypted by Voozin to post it to your webhook, so it is **not** end-to-end encrypted. Use a mailbox for mail that must stay end-to-end encrypted. ## Next - [Reply to inbound mail](https://voozin.com/docs/inbound/replying) so the conversation threads. - [Contact form to inbox](https://voozin.com/docs/guides/contact-form) for a complete example. - The [WordPress plugin](https://voozin.com/docs/wordpress) shows inbound mail in wp-admin without code. Source: https://voozin.com/docs/inbound --- # Replying to inbound mail To answer an inbound message so it appears in the same conversation in Gmail, Outlook and Apple Mail, send a normal email with two extra headers: - `In-Reply-To`: the original `message_id`, in angle brackets. - `References`: the original `references` followed by its `message_id`, each in angle brackets and separated by spaces. Also reply to the `reply_to` address when there is one, otherwise to `from`, and prefix the subject with `Re:`. ## With the Node.js SDK `inbound.reply` does all of this for you: ```ts import { Voozin, verifyWebhook } from "voozin"; const voozin = new Voozin(process.env.VOOZIN_API_KEY); export async function POST(request: Request) { const event = await verifyWebhook(await request.text(), request.headers, process.env.VOOZIN_WEBHOOK_SECRET!); if (event.type === "inbound.received") { await voozin.inbound.reply(event.data, { from: "Acme Support ", text: "Thanks for your message. We'll get back to you within a day.", }); } return new Response(null, { status: 204 }); } ``` Any other send option (`html`, `cc`, `attachments`, `tags`, `metadata`) can be passed as well. Pass `{ idempotencyKey: event.data.id }` as the third argument so a webhook retry never sends the reply twice. ## With the REST API ```bash curl https://api.voozin.com/v1/emails \ -H "Authorization: Bearer $VOOZIN_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: reply-8a4f2c1e" \ -d '{ "from": "Acme Support ", "to": ["ada@example.com"], "subject": "Re: Order #1042 hasn'\''t arrived", "text": "Thanks for your message. We'\''ll get back to you within a day.", "headers": { "In-Reply-To": "", "References": "" } }' ``` ## Reply addresses that route back to your app Send from an address that matches an inbound route, for example `support@acme.com`, or a per-conversation address such as `reply+ticket-123@acme.com` with the route pattern `reply+*`. When the customer answers, the reply arrives as another `inbound.received` event, and you can find the conversation from the recipient address or from `in_reply_to`. ## Tips - Never reply automatically to messages that look automated: skip events whose headers include `Auto-Submitted` (other than `no`), `Precedence: bulk` or `List-Id`, and empty `mail_from` (bounces). This prevents mail loops. - Quote the original text below your answer if your users expect it; it isn't added automatically. - The sending address must be on a verified domain. Source: https://voozin.com/docs/inbound/replying --- # Node.js SDK The official `voozin` package for Node.js, Bun, Deno and edge runtimes. It is written in TypeScript, has no dependencies, and uses the platform's `fetch` and Web Crypto. ```bash npm install voozin ``` Requires Node.js 20 or later. ## Set up ```ts import { Voozin } from "voozin"; const voozin = new Voozin(process.env.VOOZIN_API_KEY); ``` If you leave out the key, the client reads `VOOZIN_API_KEY` from the environment. Options: ```ts new Voozin(apiKey, { baseUrl: "https://api.voozin.com", // default maxRetries: 2, // retries for 429 and 5xx responses and network errors timeout: 30_000, // milliseconds per request }); ``` ## Emails ```ts const { id } = await voozin.emails.send( { from: "Acme ", to: ["ada@example.com"], subject: "Hi", html: "

Hello

" }, { idempotencyKey: "welcome-user-42" }, ); await voozin.emails.batch([{ … }, { … }], { idempotencyKey: "digest-2026-10-26" }); const email = await voozin.emails.get(id); const page = await voozin.emails.list({ tag: "category:receipt", limit: 50 }); // page.data, page.next_cursor await voozin.emails.reschedule(id, "2026-11-02T09:00:00Z"); await voozin.emails.cancel(id); ``` Parameters use the same `snake_case` names as the [REST API](https://voozin.com/docs/sending) (`reply_to`, `scheduled_at`, `template_id`). ## Templates ```ts const { data } = await voozin.templates.list(); const template = await voozin.templates.get("password-reset"); const preview = await voozin.templates.render({ subject: "Hi {{ name }}", html: "

Hi {{ name }}

", variables: { name: "Ada" } }); ``` ## Domains ```ts const { data: domains } = await voozin.domains.list(); // needs the domains:read scope ``` ## Webhooks ```ts import { verifyWebhook, WebhookVerificationError } from "voozin"; try { const event = await verifyWebhook(rawBody, headers, process.env.VOOZIN_WEBHOOK_SECRET!); // event.type, event.timestamp, event.data } catch (err) { if (err instanceof WebhookVerificationError) { // respond 400 } } ``` `rawBody` must be the exact request body as a string or bytes. `headers` can be a `Headers` object or a plain object. Signatures older than five minutes are rejected. `voozin.webhooks.verify(...)` does the same. Manage endpoints with `voozin.webhooks.create({ url, events })` (the response includes the `secret`), `list()`, `get(id)`, `update(id, …)` and `delete(id)`. The returned event is typed, so `event.type === "inbound.received"` narrows `event.data` to an inbound message. ## Inbound ```ts const route = await voozin.inbound.routes.create({ domain_id, pattern: "support", endpoint_id }); const { data: routes } = await voozin.inbound.routes.list(); await voozin.inbound.routes.delete(route.id); const message = await voozin.inbound.get(inboundId); const raw = await voozin.inbound.raw(inboundId); // ArrayBuffer const attachment = await voozin.inbound.attachment(inboundId, 0); // { filename, contentType, content: ArrayBuffer } await voozin.inbound.replay(inboundId); ``` ### Reply to an inbound message ```ts await voozin.inbound.reply( event.data, { from: "Acme Support ", text: "Thanks, we're on it." }, { idempotencyKey: `reply-${event.data.id}` }, ); ``` `reply` sends to the message's `reply_to` (or `from`) address, sets `Re:` on the subject, and sets `In-Reply-To` and `References` so the reply threads. See [Replying to inbound mail](https://voozin.com/docs/inbound/replying). ## Next.js helper ```ts // app/api/webhooks/voozin/route.ts import { createWebhookHandler } from "voozin/next"; export const POST = createWebhookHandler({ secret: process.env.VOOZIN_WEBHOOK_SECRET!, async onEvent(event) { if (event.type === "email.bounced") await markBounced(event.data.recipient); }, }); ``` The handler reads the raw body, verifies it, calls `onEvent`, and responds `204` (or `400` for a bad signature). See the [Next.js guide](https://voozin.com/docs/guides/nextjs). ## Express helper ```ts import express from "express"; import { webhookHandler } from "voozin/express"; const app = express(); app.post( "/webhooks/voozin", express.raw({ type: "application/json" }), webhookHandler({ secret: process.env.VOOZIN_WEBHOOK_SECRET!, onEvent: async (event) => { /* … */ } }), ); ``` Mount it with `express.raw` (or before any JSON body parser) so the signature can be checked against the raw body. See the [Express guide](https://voozin.com/docs/guides/express). ## Errors API errors throw `VoozinError` with `statusCode`, `error`, `message` and, for batch requests, `index`: ```ts import { VoozinError } from "voozin"; try { await voozin.emails.send(params); } catch (err) { if (err instanceof VoozinError && err.statusCode === 402) { // the plan doesn't include transactional email, or billing lapsed } throw err; } ``` `429` and `5xx` responses and network errors are retried with backoff (respecting `Retry-After`) up to `maxRetries` times. Requests with an `idempotencyKey` are always safe to retry. ## Source The package is open source (MIT): [github.com/voozin/voozin-node](https://github.com/voozin/voozin-node). Source: https://voozin.com/docs/sdk/node --- # WordPress plugin The Voozin plugin sends every email WordPress and your plugins send (password resets, WooCommerce orders, form notifications) through the Voozin API instead of the server's PHP mail. It also receives email: messages to an address such as `support@yoursite.com` appear in an inbox inside wp-admin, grouped into conversations, and you can reply from there. - Works with WordPress 6.2+ and PHP 7.4+. - No SMTP plugin needed; mail goes over HTTPS, so it works on hosts that block SMTP ports. - Free and open source (GPLv2 or later). ## Install - From WordPress: **Plugins → Add New**, search for **Voozin**, then **Install** and **Activate**. - Or download [voozin-wordpress.zip](https://voozin.com/downloads/voozin-wordpress.zip) and upload it under **Plugins → Add New → Upload Plugin**. ## Connect your account 1. In Voozin, [verify your domain](https://voozin.com/docs/domains) and create an API key under **Developers → API keys** with the scopes `emails:send` and `domains:read`. For the inbox, also add `webhooks` and `inbound`. 2. In WordPress, open **Voozin → Settings** and paste the key. To keep it out of the database, add it to `wp-config.php` instead: ```php define( 'VOOZIN_API_KEY', 'ic_live_...' ); ``` 3. Choose the **From** address: pick one of your verified domains from the list and enter the address and name, for example `WordPress `. 4. Click **Send test email**. From now on, every call to `wp_mail()` goes through Voozin. Plugins that set their own From address on a verified domain keep it; other From addresses are replaced with yours, so mail is never sent from a domain that would fail SPF and DKIM. ## Settings | Setting | What it does | | --- | --- | | From address and name | The default sender for WordPress mail | | Force From address | Always use your From address, even when a plugin sets another one | | Fallback to PHP mail | If the Voozin API cannot be reached or rejects an email, send it with WordPress's default mailer instead of failing. The log shows the Voozin error. | | Track opens and clicks | Overrides your domain's tracking defaults for WordPress mail | | Keep log for | How long the email log is kept (default 30 days) | ## Email log **Voozin → Email log** lists every email WordPress sent: time, recipient, subject, and status. When the inbox is connected, the status updates from delivery webhooks (delivered, bounced, complained), so you can see why a customer never got their password reset. ## Inbox: receive and reply 1. Open **Voozin → Inbox** and click **Connect**. The plugin creates a webhook endpoint in Voozin pointing to `https://yoursite.com/wp-json/voozin/v1/webhook` and stores its signing secret. 2. Under **Receiving addresses**, enter the address to receive and choose the domain, for example `support`, a prefix such as `reply+*`, or `*` for every address without a mailbox. Click **Add address** to create the inbound route. 3. Repeat for more addresses. **Disconnect this site** deletes the webhook and routes in Voozin. Your domain's `MX` record must point to Voozin (the domain page in Voozin shows it). Received messages appear under **Voozin → Inbox**, grouped into conversations by their `In-Reply-To` and `References` headers. Open one to read it, download attachments, and reply. Replies are sent from the address the message was sent to and thread in the sender's mail app. Your WordPress site must be reachable from the internet over HTTPS to receive webhooks. ## For developers When a message arrives, the plugin fires an action with the stored post id and the full [inbound.received](https://voozin.com/docs/inbound) data: ```php add_action( 'voozin_inbound_received', function ( int $post_id, array $message ) { if ( 0 === strpos( $message['subject'] ?? '', '[Order' ) ) { // create a WooCommerce order note, a ticket, a lead… } }, 10, 2 ); ``` Other hooks: - `voozin_event_received` (`$event`): every verified webhook event, including `email.*` events. - `voozin_email_payload` (filter, `$payload`, `$atts`): change the API request before it is sent, for example to add `tags`. Messages are stored as a private post type (`voozin_message`) and are not visible on the front end. Uninstalling the plugin deletes its settings, log and stored messages, and removes the webhook and routes it created in Voozin. ## Troubleshooting - **Test email fails with 403**: the key is missing the `emails:send` scope, or it is restricted to another domain. - **Test email fails with 402**: the organization's plan doesn't include transactional email, or the trial has reached its included amount. - **The inbox stays empty**: check the domain's `MX` record and the delivery log of the webhook in Voozin (**Developers → Webhooks**). Security plugins and firewalls must allow `POST` requests to `/wp-json/voozin/v1/webhook`. Source: https://voozin.com/docs/wordpress --- # Mail and calendar apps Voozin mailboxes work in any app that speaks IMAP, SMTP and CalDAV: Apple Mail and Calendar, Thunderbird, Outlook, Thunderbird for Android, K-9 Mail and others. Most apps find the settings themselves from the email address. ## Settings | Setting | Value | | --- | --- | | Incoming (IMAP) | `imap.inboxcluster.net`, port `993`, SSL/TLS | | Outgoing (SMTP) | `smtp.inboxcluster.net`, port `465` with SSL/TLS, or `587` with STARTTLS | | Calendar (CalDAV) | `https://mail.voozin.com/dav/` | | User name | The full mailbox address, for example `ann@acme.com` | | Password | An app password for that mailbox | The dashboard's **Connect** dialog next to each mailbox shows the same settings. Connections without TLS are refused. Mailboxes with end-to-end encryption have no CalDAV, because their calendars are encrypted in the browser. ## App passwords Mail apps don't use your account password. Create an app password for each device: 1. In the dashboard open **Mailboxes** and click **Connect** next to the mailbox. 2. Enter a name such as "Thunderbird on laptop" and click **Create**. The password is shown once. 3. Paste it into the app as the password. Revoke an app password from the same dialog when a device is lost. Repeated wrong passwords temporarily block the device's IP address. ## Automatic setup Enter the email address and the app password; the app fills in the servers. - **Thunderbird and Thunderbird for Android** read the settings from `autoconfig.inboxcluster.net`, which they find through your domain's MX record. Nothing extra is needed in your DNS. - **Outlook** (classic, for IMAP accounts) uses autodiscover. Add this SRV record to your domain: | Type | Name | Priority | Weight | Port | Target | | --- | --- | --- | --- | --- | --- | | SRV | `_autodiscover._tcp` | `0` | `0` | `443` | `autodiscover.voozin.com` | - **Other apps** that ask for servers: use the settings above. ## iPhone, iPad and Mac In the **Connect** dialog click **Set up on iPhone or Mac**. It downloads a profile with a new app password that adds the mailbox to Mail, and to Calendar for standard mailboxes. - **iPhone and iPad:** open the file, then go to **Settings → Profile Downloaded** and tap **Install**. - **Mac:** open the file, then go to **System Settings → General → Device Management** (or **Profiles**) and click **Install**. The device shows the profile as unverified because it isn't signed; that's expected. Removing the profile removes the account. The app password inside it stays valid until you revoke it in the dashboard. ## Signing in with your Voozin account Apps that support [Sign in with Voozin](https://voozin.com/docs/sign-in-with-voozin) connect without an app password: they open a browser window where you sign in to Voozin and approve access to mail and calendars. You can disconnect them under **Account and security → Connected apps**. Thunderbird offers this once Voozin is in its built-in list of sign-in providers; until then, use an app password in Thunderbird. Apple Mail, Outlook and Gmail only offer browser sign-in for their own list of providers, so they use app passwords. Source: https://voozin.com/docs/mail-clients --- # Sign in with Voozin Voozin is an OAuth 2.1 and OpenID Connect provider. Websites and apps can let people sign in with their Voozin account, and mail apps can connect to a mailbox over IMAP, SMTP and CalDAV without an app password. Every app asks for consent, and people can disconnect it at any time. ## Register an app 1. In the dashboard open **Developers → Developer apps** and click **Create app**. You need a role that can manage developer settings, the same as for API keys and webhooks. 2. Choose the type: - **Website**: your server keeps a client secret. Redirect URIs use `https` (`http://localhost` works for development). - **App**: desktop and mobile apps that can't keep a secret, so they sign in with PKCE alone. Redirect URIs are loopback addresses such as `http://127.0.0.1/callback` (any port is accepted at sign-in) or a private-use scheme such as `com.example.app:/oauth`. 3. Tick **Mail and calendar access** if the app needs IMAP, SMTP or CalDAV. 4. Optionally add **Sign-out redirect URIs**: the pages people may return to after signing out of your app (see [Signing out](#signing-out)). They follow the same rules as redirect URIs. 5. Copy the client ID, and for websites the client secret. The secret is shown once; rotate it from the same page if it leaks. The name and homepage you enter are shown on the consent screen. ## Endpoints The issuer is `https://auth.voozin.com`. Libraries that support discovery only need the issuer. | Endpoint | URL | | --- | --- | | Discovery | `https://auth.voozin.com/.well-known/openid-configuration` | | Authorization | `https://auth.voozin.com/api/auth/oauth2/authorize` | | Token | `https://auth.voozin.com/api/auth/oauth2/token` | | User info | `https://auth.voozin.com/api/auth/oauth2/userinfo` | | Keys (JWKS) | `https://auth.voozin.com/api/auth/jwks` | | Revocation | `https://auth.voozin.com/api/auth/oauth2/revoke` | | Sign-out | `https://auth.voozin.com/api/auth/oauth2/end-session` | Websites authenticate to the token endpoint with HTTP Basic (`client_secret_basic`). Every authorization request needs PKCE with `S256`, websites included. ## Scopes | Scope | Grants | | --- | --- | | `openid` | An ID token with the user's ID in `sub`. | | `profile` | The user's name. | | `email` | The user's email address and whether it is verified. | | `offline_access` | A refresh token, so the app stays signed in after the access token expires. | | `mail` | IMAP and SMTP for mailboxes the user can open. Needs **Mail and calendar access**. | | `calendar` | CalDAV for those mailboxes' calendars. Needs **Mail and calendar access**. | Access tokens last one hour. `sub` is a stable user ID; use it, not the email address, to link accounts. ## Node.js example A website using [openid-client](https://github.com/panva/openid-client) (version 6) and Express: ```ts import express from "express"; import session from "express-session"; import * as client from "openid-client"; const config = await client.discovery( new URL("https://auth.voozin.com"), process.env.VOOZIN_CLIENT_ID!, undefined, client.ClientSecretBasic(process.env.VOOZIN_CLIENT_SECRET!), ); const redirectUri = "https://example.com/auth/callback"; const app = express(); app.use(session({ secret: process.env.SESSION_SECRET!, resave: false, saveUninitialized: false })); app.get("/auth/voozin", async (req, res) => { const verifier = client.randomPKCECodeVerifier(); const state = client.randomState(); req.session.oauth = { verifier, state }; const url = client.buildAuthorizationUrl(config, { redirect_uri: redirectUri, scope: "openid email profile", code_challenge: await client.calculatePKCECodeChallenge(verifier), code_challenge_method: "S256", state, }); res.redirect(url.href); }); app.get("/auth/callback", async (req, res) => { const { verifier, state } = req.session.oauth ?? {}; const tokens = await client.authorizationCodeGrant(config, new URL(req.originalUrl, "https://example.com"), { pkceCodeVerifier: verifier, expectedState: state, }); const claims = tokens.claims()!; req.session.user = { id: claims.sub, email: claims.email, name: claims.name }; req.session.idToken = tokens.id_token; // needed to sign out res.redirect("/"); }); ``` ## PKCE without a library Apps follow the same steps by hand. 1. Make a random `code_verifier` (43 to 128 characters) and its challenge: the base64url SHA-256 hash of the verifier. 2. Open the authorization URL in the system browser: ```text https://auth.voozin.com/api/auth/oauth2/authorize ?response_type=code &client_id=YOUR_CLIENT_ID &redirect_uri=http%3A%2F%2F127.0.0.1%3A53682%2Fcallback &scope=openid%20email%20mail%20offline_access &state=RANDOM_STATE &code_challenge=CODE_CHALLENGE &code_challenge_method=S256 ``` 3. The user signs in, approves the app and comes back to your redirect URI with `code`, `state` and `iss`. Check that `state` matches and `iss` is `https://auth.voozin.com`. 4. Exchange the code: ```bash curl https://auth.voozin.com/api/auth/oauth2/token \ -d grant_type=authorization_code \ -d client_id=YOUR_CLIENT_ID \ -d code=CODE_FROM_REDIRECT \ -d redirect_uri=http://127.0.0.1:53682/callback \ -d code_verifier=CODE_VERIFIER ``` The response has `access_token`, `expires_in`, `id_token` (with `openid`) and `refresh_token` (with `offline_access`). Get a new access token with `grant_type=refresh_token`; each refresh returns a new refresh token, so store it. ## Signing out Signing someone out of your app never signs them out of Voozin. They stay signed in to the Voozin dashboard, webmail and other apps, and the next **Sign in with Voozin** goes straight through without a password. Add `prompt=login` to the authorization URL if you want Voozin to ask for the password again. To sign someone out, clear your own session, then send the browser to the sign-out endpoint. Voozin revokes the tokens your app got from that sign-in, including the refresh token, and sends the person back to you. | Parameter | | | --- | --- | | `id_token_hint` | The ID token you got at sign-in. Voozin uses it to find which tokens to revoke. | | `client_id` | Your client ID. Needed when you don't send `id_token_hint`. | | `post_logout_redirect_uri` | Optional. Where to send them afterwards. It must exactly match one of the app's **Sign-out redirect URIs**; otherwise Voozin shows an error. Without it, Voozin shows a "Signed out" page. | | `state` | Optional. Returned on the redirect as `state`. | With openid-client, continuing the example above (add `https://example.com/signed-out` under **Sign-out redirect URIs** first): ```ts app.post("/logout", (req, res) => { const idToken = req.session.idToken; req.session.destroy(() => {}); const url = client.buildEndSessionUrl(config, { id_token_hint: idToken!, post_logout_redirect_uri: "https://example.com/signed-out", }); res.redirect(url.href); }); ``` Without a library, redirect to: ```text https://auth.voozin.com/api/auth/oauth2/end-session ?id_token_hint=ID_TOKEN &post_logout_redirect_uri=https%3A%2F%2Fexample.com%2Fsigned-out &state=RANDOM_STATE ``` Apps that don't want a redirect, such as desktop and mobile apps, can revoke the refresh token at the revocation endpoint instead and then forget their tokens: ```bash curl https://auth.voozin.com/api/auth/oauth2/revoke \ -d client_id=YOUR_CLIENT_ID \ -d token=REFRESH_TOKEN \ -d token_type_hint=refresh_token ``` Websites send their client secret with HTTP Basic, as at the token endpoint. ID tokens issued before 13 November 2026 don't name the sign-in, so for those the sign-out endpoint only redirects; revoke the refresh token as above. ## Mail and calendar access With the `mail` scope, the access token signs in to IMAP and SMTP with SASL `XOAUTH2` or `OAUTHBEARER`. With `calendar`, it signs in to CalDAV as a `Bearer` token. | Service | Server | | --- | --- | | IMAP | `imap.inboxcluster.net`, port `993` (TLS) | | SMTP | `smtp.inboxcluster.net`, port `465` (TLS) or `587` (STARTTLS) | | CalDAV | `https://mail.voozin.com/dav/` | The user name is the mailbox address, for example `ann@acme.com`. The token's user must be able to open that mailbox in Voozin; a token works for every mailbox they can open. For CalDAV, `https://mail.voozin.com/dav/` opens the mailbox at the user's own address (or their only mailbox); for any other mailbox, use its principal URL, such as `https://mail.voozin.com/dav/principals/ann@acme.com/`. An `XOAUTH2` login is the base64 encoding of: ```text user=ann@acme.com^Aauth=Bearer ACCESS_TOKEN^A^A ``` where `^A` is the byte `0x01`. With Nodemailer: ```ts const transport = nodemailer.createTransport({ host: "smtp.inboxcluster.net", port: 465, secure: true, auth: { type: "OAuth2", user: "ann@acme.com", accessToken }, }); ``` When a token is expired or lacks the scope, the server answers with a JSON challenge as in [RFC 7628](https://www.rfc-editor.org/rfc/rfc7628): `{"status":"invalid_token","scope":"mail","openid-configuration":"https://auth.voozin.com/.well-known/openid-configuration"}`. Reply with the dummy response `AQ==` (the byte `0x01`), which fails the login, then refresh the token and sign in again. CalDAV answers `401` with a `WWW-Authenticate: Bearer` header naming the missing scope. Mailboxes with end-to-end encryption have no CalDAV. ## Revoking access People see the apps they've approved under **Account and security → Connected apps** in the dashboard, and **Disconnect** revokes the app's tokens at once. Apps can revoke their own refresh token at the revocation endpoint when someone signs out (see [Signing out](#signing-out)). Disabling or deleting an app under **Developer apps** stops it for everyone. ## Sign in with Voozin button Use the official button, in [dark](https://voozin.com/sign-in-with-voozin.svg) or [light](https://voozin.com/sign-in-with-voozin-light.svg): ![Sign in with Voozin](https://voozin.com/sign-in-with-voozin.svg) ![Sign in with Voozin, light](https://voozin.com/sign-in-with-voozin-light.svg) ```html Sign in with Voozin ``` Source: https://voozin.com/docs/sign-in-with-voozin --- # Send and receive email with Next.js This guide uses the App Router. It sends a welcome email from a server action and receives delivery and inbound events in a route handler. ## 1. Install and configure ```bash npm install voozin ``` ```bash # .env.local VOOZIN_API_KEY=ic_live_... VOOZIN_WEBHOOK_SECRET=whsec_... ``` Create one client for the app: ```ts // lib/voozin.ts import { Voozin } from "voozin"; export const voozin = new Voozin(process.env.VOOZIN_API_KEY); ``` ## 2. Send from a server action ```tsx // app/signup/actions.ts "use server"; import { voozin } from "@/lib/voozin"; export async function signUp(formData: FormData) { const email = String(formData.get("email")); const user = await createUser(email); await voozin.emails.send( { from: "Acme ", to: [email], subject: "Welcome to Acme", html: `

Hi! Confirm your account: confirm

`, tags: { category: "welcome" }, metadata: { user_id: user.id }, }, { idempotencyKey: `welcome-${user.id}` }, ); } ``` The API key stays on the server: server actions and route handlers never ship it to the browser. To use React components for email HTML, render them to a string first (for example with `@react-email/render`) and pass the result as `html`. ## 3. Receive webhooks Add an endpoint in Voozin (**Developers → Webhooks**) with the URL `https://your-app.com/api/webhooks/voozin`, then: ```ts // app/api/webhooks/voozin/route.ts import { createWebhookHandler } from "voozin/next"; import { voozin } from "@/lib/voozin"; export const POST = createWebhookHandler({ secret: process.env.VOOZIN_WEBHOOK_SECRET!, async onEvent(event) { switch (event.type) { case "email.bounced": await markEmailInvalid(event.data.recipient); break; case "inbound.received": await saveTicket(event.data); await voozin.inbound.reply( event.data, { from: "Acme Support ", text: "Thanks, we got your message." }, { idempotencyKey: `ack-${event.data.id}` }, ); break; } }, }); ``` `createWebhookHandler` reads the raw body, checks the signature and timestamp, and returns `400` for invalid requests. Keep `onEvent` fast; queue long work (for example with `after()` from `next/server`) so Voozin gets a response within 10 seconds. ## 4. Test locally Webhook URLs must be public HTTPS. While developing, expose your dev server with a tunnel (for example `cloudflared tunnel --url http://localhost:3000`) and use that URL for a test endpoint. Use **Replay** on any delivery in the dashboard to resend an event to your handler. ## Deploying on Vercel Add `VOOZIN_API_KEY` and `VOOZIN_WEBHOOK_SECRET` under **Project → Settings → Environment Variables**. The SDK works in the Node.js and Edge runtimes. Source: https://voozin.com/docs/guides/nextjs --- # Send and receive email with Express ## Install ```bash npm install voozin express ``` ## Send email ```ts import express from "express"; import { Voozin, VoozinError } from "voozin"; const voozin = new Voozin(process.env.VOOZIN_API_KEY); const app = express(); app.post("/password-reset", express.json(), async (req, res) => { const user = await findUserByEmail(req.body.email); if (user) { const token = await createResetToken(user); try { await voozin.emails.send( { from: "Acme ", to: [user.email], template_id: "password-reset", variables: { first_name: user.firstName, reset_url: `https://acme.com/reset/${token.value}` }, }, { idempotencyKey: `reset-${token.id}` }, ); } catch (err) { if (err instanceof VoozinError) console.error("Voozin", err.statusCode, err.message); throw err; } } res.status(204).end(); }); ``` ## Receive webhooks The signature is computed over the raw body, so the webhook route must not go through `express.json()`. Use `express.raw` on that route: ```ts import { webhookHandler } from "voozin/express"; app.post( "/webhooks/voozin", express.raw({ type: "application/json" }), webhookHandler({ secret: process.env.VOOZIN_WEBHOOK_SECRET!, async onEvent(event) { if (event.type === "inbound.received") { await tickets.createFromEmail(event.data); } }, }), ); ``` `webhookHandler` responds `204` after `onEvent` resolves, `400` for an invalid signature, and passes other errors to Express's error handler, so Voozin retries the delivery. If you mount a global `express.json()`, register the webhook route before it. ## Without the helper ```ts import { verifyWebhook, WebhookVerificationError } from "voozin"; app.post("/webhooks/voozin", express.raw({ type: "application/json" }), async (req, res) => { try { const event = await verifyWebhook(req.body, req.headers, process.env.VOOZIN_WEBHOOK_SECRET!); await handle(event); res.status(204).end(); } catch (err) { res.status(err instanceof WebhookVerificationError ? 400 : 500).end(); } }); ``` The same code works with Fastify (`request.rawBody` with `fastify-raw-body`), Hono (`await c.req.text()`) and plain `node:http`. Source: https://voozin.com/docs/guides/express --- # Send and receive email with PHP and Laravel Voozin's API is plain HTTPS and JSON, so any PHP version with cURL works. For WordPress, use the [plugin](https://voozin.com/docs/wordpress). ## Plain PHP ```php true, CURLOPT_HTTPHEADER => $headers, CURLOPT_POSTFIELDS => json_encode($email), CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 30, ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE); curl_close($ch); $data = json_decode((string) $body, true); if ($status >= 400) throw new RuntimeException($data['message'] ?? "Voozin error $status"); return $data; } voozin_send([ 'from' => 'Acme ', 'to' => ['ada@example.com'], 'subject' => 'Order #1042 confirmed', 'html' => '

Thanks for your order!

', ], 'order-1042-confirmation'); ``` ## Laravel Add the key to `.env` and `config/services.php`: ```php // config/services.php 'voozin' => [ 'key' => env('VOOZIN_API_KEY'), 'webhook_secret' => env('VOOZIN_WEBHOOK_SECRET'), ], ``` Send with the HTTP client: ```php use Illuminate\Support\Facades\Http; Http::withToken(config('services.voozin.key')) ->withHeaders(['Idempotency-Key' => "order-{$order->id}-confirmation"]) ->retry(3, 500, throw: false) ->post('https://api.voozin.com/v1/emails', [ 'from' => 'Acme ', 'to' => [$order->email], 'subject' => "Order #{$order->id} confirmed", 'html' => view('emails.order-confirmed', ['order' => $order])->render(), ]) ->throw(); ``` To keep using Laravel's `Mail` facade and Mailables, configure the SMTP mailer with a Voozin mailbox and app password (see [SMTP](https://voozin.com/docs/smtp)): ```bash MAIL_MAILER=smtp MAIL_HOST=smtp.inboxcluster.net MAIL_PORT=587 MAIL_USERNAME=no-reply@acme.com MAIL_PASSWORD=your-app-password MAIL_FROM_ADDRESS=no-reply@acme.com ``` ## Receive webhooks in Laravel ```php // routes/api.php Route::post('/webhooks/voozin', function (Illuminate\Http\Request $request) { $raw = $request->getContent(); $headers = [ 'webhook-id' => $request->header('webhook-id'), 'webhook-timestamp' => $request->header('webhook-timestamp'), 'webhook-signature' => $request->header('webhook-signature'), ]; abort_unless(voozin_verify_webhook(config('services.voozin.webhook_secret'), $headers, $raw), 400); $event = json_decode($raw, true); if ($event['type'] === 'inbound.received') { App\Jobs\HandleInboundEmail::dispatch($event['data']); } return response()->noContent(); }); ``` `voozin_verify_webhook` is the PHP function from [Webhooks](https://voozin.com/docs/webhooks#verify-the-signature). Routes in `routes/api.php` are exempt from CSRF checks. Source: https://voozin.com/docs/guides/php --- # Contact form to inbox A contact form that emails your team, sends the visitor a confirmation, and lets your team reply straight from their inbox. It uses Next.js, but the same calls work from any backend. ## How it works 1. The form posts to your server. 2. Your server sends the message to your team's mailbox, with `reply_to` set to the visitor, so pressing **Reply** in the webmail answers the visitor directly. 3. Your server sends the visitor a short confirmation. Optional: give the form its own address, such as `hello@acme.com`, as an [inbound route](https://voozin.com/docs/inbound) to store every conversation in your app too. ## Server action ```ts // app/contact/actions.ts "use server"; import { voozin } from "@/lib/voozin"; export async function sendContact(_: unknown, formData: FormData) { const name = String(formData.get("name") ?? "").slice(0, 100); const email = String(formData.get("email") ?? ""); const message = String(formData.get("message") ?? "").slice(0, 5000); if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email) || !message) return { ok: false, error: "Please fill in all fields." }; if (formData.get("website")) return { ok: true }; // honeypot field, hidden from people const id = crypto.randomUUID(); await voozin.emails.send( { from: "Acme website ", to: ["team@acme.com"], reply_to: `${name} <${email}>`, subject: `Contact form: ${name}`, text: `${message}\n\n— ${name} <${email}>`, tags: { category: "contact-form" }, }, { idempotencyKey: `contact-${id}-team` }, ); await voozin.emails.send( { from: "Acme ", to: [email], subject: "We got your message", text: `Hi ${name},\n\nThanks for contacting Acme. We usually reply within one business day.\n\nYour message:\n${message}`, }, { idempotencyKey: `contact-${id}-ack` }, ); return { ok: true }; } ``` ## Form ```tsx // app/contact/page.tsx "use client"; import { useActionState } from "react"; import { sendContact } from "./actions"; export default function ContactPage() { const [state, action, pending] = useActionState(sendContact, null); if (state?.ok) return

Thanks! We'll be in touch.

; return (