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

npm install voozin
# .env.local
VOOZIN_API_KEY=ic_live_...
VOOZIN_WEBHOOK_SECRET=whsec_...

Create one client for the app:

// lib/voozin.ts
import { Voozin } from "voozin";
 
export const voozin = new Voozin(process.env.VOOZIN_API_KEY);

2. Send from a server action

// 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 <hello@acme.com>",
      to: [email],
      subject: "Welcome to Acme",
      html: `<p>Hi! Confirm your account: <a href="https://acme.com/confirm/${user.token}">confirm</a></p>`,
      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:

// 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 <support@acme.com>", 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.