Send email from Next.js

​

Prerequisites

• A Nuntly account. The free plan includes 3,000 emails per month (100 per day) and needs no credit card. See account setup.
• A verified sending domain. See sending domains.
• An API key with the Sending only permission. See API keys. You store it in an environment variable in the next section.
• A Next.js project that uses the App Router. The samples use the app/ directory and the @/ import alias that create-next-app configures.

​

Install and configure the SDK

npm install @nuntly/sdk

pnpm add @nuntly/sdk

yarn add @nuntly/sdk

bun add @nuntly/sdk

NUNTLY_API_KEY=ntly_your_api_key

import { Nuntly } from '@nuntly/sdk';

export const nuntly = new Nuntly({ apiKey: process.env.NUNTLY_API_KEY });

​

Send your first email

'use server';

import { APIError } from '@nuntly/sdk';
import { nuntly } from '@/lib/nuntly';

export type SendState = { ok: boolean; message: string };

export async function sendWelcomeEmail(_prev: SendState, formData: FormData): Promise<SendState> {
  const to = String(formData.get('email') ?? '').trim();
  if (!to.includes('@')) {
    return { ok: false, message: 'Enter a valid email address.' };
  }

  try {
    const email = await nuntly.emails.send({
      from: 'Acme <hello@yourdomain.com>',
      to,
      subject: 'Welcome to Acme',
      html: '<p>Your account is ready. <a href="https://yourdomain.com/login">Sign in</a>.</p>',
      text: 'Your account is ready. Sign in at https://yourdomain.com/login',
      tags: [{ name: 'category', value: 'welcome' }],
    });

    console.info('Welcome email accepted', { emailId: email.id, status: email.status });
    return { ok: true, message: 'Check your inbox.' };
  } catch (error) {
    if (error instanceof APIError) {
      console.error('Welcome email rejected', { status: error.status, code: error.code, requestId: error.requestId });
    } else {
      console.error('Welcome email failed', error);
    }
    return { ok: false, message: 'The email could not be sent. Try again in a minute.' };
  }
}

'use client';

import { useActionState } from 'react';
import { sendWelcomeEmail, type SendState } from '@/app/actions/send-welcome-email';

const initialState: SendState = { ok: false, message: '' };

export function SignupForm() {
  const [state, formAction, pending] = useActionState(sendWelcomeEmail, initialState);

  return (
    <form action={formAction}>
      <label htmlFor="email">Email</label>
      <input id="email" name="email" type="email" required />
      <button type="submit" disabled={pending}>
        {pending ? 'Sending...' : 'Create account'}
      </button>
      <p aria-live="polite">{state.message}</p>
    </form>
  );
}

import { SignupForm } from './signup-form';

export default function SignupPage() {
  return <SignupForm />;
}

​

Server Action or Route Handler

​

Observe what happened

​

Email timeline in the dashboard

​

Receive webhooks in a Route Handler

NUNTLY_WEBHOOK_SECRET=whsec_your_signing_secret

import { verifyWebhook, WebhookVerificationError } from '@nuntly/sdk';

export async function POST(request: Request) {
  const payload = await request.text();
  const signature = request.headers.get('webhook-signature') ?? '';

  let event;
  try {
    event = await verifyWebhook(payload, signature, process.env.NUNTLY_WEBHOOK_SECRET ?? '');
  } catch (error) {
    if (error instanceof WebhookVerificationError) {
      return new Response('Invalid signature', { status: 401 });
    }
    throw error;
  }

  switch (event.type) {
    case 'email.delivered':
      console.info('Email delivered', { emailId: event.data.id, eventId: event.id });
      break;
    case 'email.bounced':
      console.warn('Email bounced', {
        emailId: event.data.id,
        bounceType: event.data.bounce.bounceType,
      });
      break;
    case 'email.complained':
      console.warn('Spam complaint', { emailId: event.data.id });
      break;
    default:
      console.info('Unhandled event', { type: event.type, eventId: event.id });
  }

  return Response.json({ received: true });
}

• The raw body. The signature covers the exact bytes Nuntly sent, so read them with request.text(). Parsing with request.json() and serializing again breaks verification. Route Handlers expose the raw body without any bodyParser configuration.
• A 401 on a bad signature. verifyWebhook throws WebhookVerificationError when the signature does not match, the header is malformed, or the timestamp is more than 5 minutes away from the current time, which blocks replayed requests.
• Typed events. The event is a union typed on event.type, so inside case 'email.bounced' TypeScript knows that event.data.bounce exists. A Permanent bounce type means the address cannot receive mail: stop sending to it.
• A fast 2xx. Any response other than 2xx counts as a failed delivery. Respond first and move slow work out of the request path.

​

Production notes

​

Idempotency keys

await nuntly.emails.send(
  {
    from: 'Acme <hello@yourdomain.com>',
    to: user.email,
    subject: 'Welcome to Acme',
    html: '<p>Your account is ready.</p>',
  },
  { idempotencyKey: `welcome-${user.id}` },
);

​

Retries

​

Error handling

​

Separate environments

​

What not to log

• Log the em_ email ID, the evt_ event ID and the requestId. They identify the email without identifying the person.
• Do not log to, from, subject, the HTML body, or a full webhook payload. A console.log(event) in the webhook handler writes a recipient address to your logs on every delivery.
• To investigate a support request, take the email ID from your logs and open the email in the dashboard.

​

Next steps

​

Other frameworks