# 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 <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:

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