NextAuth (Auth.js) email provider: send magic links through Nuntly
Send NextAuth and Auth.js magic link emails through Nuntly with a custom HTTP email provider or SMTP, on v4 and v5, and map that email to Better Auth when you migrate.
Passwordless sign-in with NextAuth depends on one email: the magic link. If it lands late or fails to send, your user waits on a "check your email" page and gives up.
You will configure the NextAuth email provider to send that email through Nuntly, either with the Nuntly SDK or over SMTP, on Auth.js v5 and NextAuth v4. The Better Auth team now maintains Auth.js, so the last section maps the same email to Better Auth for when you migrate.
What the NextAuth email provider sends
The NextAuth email provider sends one email: a sign-in link. Auth.js stores a verification token, emails a link that carries it, and signs the user in when they click. The Auth.js email documentation (read 2026-11-14) describes no other email.
Email provider: the Auth.js provider type for passwordless sign-in, where sendVerificationRequest delivers a one-time link by email.
Two facts from that page shape the setup:
- The link is valid for 24 hours by default. The provider's
maxAgeoption, in seconds, changes that. - An email provider needs a database adapter, because the verification token has to be stored. This holds with JWT sessions too.
The examples below assume your auth.ts already has an adapter. They use Prisma; any Auth.js adapter works the same way.
Two versions are in use today. On npm, the latest tag of next-auth is 4.24.15 and the beta tag is 5.0.0-beta.32 (npm versions, read 2026-11-14). The v5 docs live on authjs.dev, the v4 docs on next-auth.js.org. Each step below starts with v5 and gives the v4 difference.
Send NextAuth (Auth.js) emails with the Nuntly SDK
Auth.js documents a custom HTTP email provider (read 2026-11-14): a provider object of type email whose sendVerificationRequest calls your email API. That is the route for the Nuntly SDK.
Step 1: Install the SDK and set the API key
npm install @nuntly/sdk
Add your API key to .env.local:
NUNTLY_API_KEY=ntly_your_api_key
The from address must be on a domain you added and verified in Nuntly (see sending domains). Until then, the send fails with the domain_not_verified error code.
Step 2: Write the send function
Auth.js calls sendVerificationRequest with identifier (the user's email address) and url (the sign-in link). This function sends both through the SDK:
// lib/send-sign-in-email.tsimport { Nuntly } from '@nuntly/sdk';const nuntly = new Nuntly({ apiKey: process.env.NUNTLY_API_KEY });export async function sendSignInEmail({ identifier, url }: { identifier: string; url: string }) {const { host } = new URL(url);await nuntly.emails.send({from: 'Acme <auth@acme.com>',to: identifier,subject: `Sign in to ${host}`,text: `Sign in to ${host}:\n${url}\n\nIf you did not request this email, ignore it.`,html: `<p><a href="${url}">Sign in to ${host}</a></p><p>If you did not request this email, ignore it.</p>`,});}
The SDK throws a typed error when the API rejects the send. Auth.js catches it, so you don't need a try block here.
The function takes only the two fields it uses, so the same file works with v5, v4 and Better Auth.
Step 3: Register the provider in Auth.js v5
// auth.tsimport NextAuth from 'next-auth';import { PrismaAdapter } from '@auth/prisma-adapter';import { prisma } from '@/lib/prisma';import { sendSignInEmail } from '@/lib/send-sign-in-email';export const { handlers, auth, signIn, signOut } = NextAuth({adapter: PrismaAdapter(prisma),providers: [{id: 'nuntly',type: 'email',name: 'Email',maxAge: 60 * 60 * 24,sendVerificationRequest: sendSignInEmail,},],});
The route handler stays the standard one:
// app/api/auth/[...nextauth]/route.tsimport { handlers } from '@/auth';export const { GET, POST } = handlers;
A server action starts the sign-in. The first argument is the provider id:
// app/sign-in/page.tsximport { signIn } from '@/auth';export default function SignIn() {return (<formaction={async (formData) => {'use server';await signIn('nuntly', formData);}}><input type="email" name="email" placeholder="you@example.com" required /><button type="submit">Email me a sign-in link</button></form>);}
On submit, Auth.js stores the token and calls sendSignInEmail in parallel, then redirects to /api/auth/verify-request.
NextAuth v4: pass the function to EmailProvider
In v4, keep the built-in EmailProvider and replace its sendVerificationRequest:
// pages/api/auth/[...nextauth].tsimport NextAuth, { type NextAuthOptions } from 'next-auth';import EmailProvider from 'next-auth/providers/email';import { PrismaAdapter } from '@next-auth/prisma-adapter';import { prisma } from '@/lib/prisma';import { sendSignInEmail } from '@/lib/send-sign-in-email';export const authOptions: NextAuthOptions = {adapter: PrismaAdapter(prisma),providers: [EmailProvider({sendVerificationRequest: sendSignInEmail,}),],};export default NextAuth(authOptions);
Install nodemailer anyway (npm install nodemailer@7). The v4 next-auth/providers/email module imports it when it loads, even if your function never uses it. The provider id is email, so the client call is signIn('email', { email }) from next-auth/react.
Send your first magic link through Nuntly
Free plan available. No credit card required.
Start for freeSend NextAuth emails over SMTP with Nodemailer
The built-in Nodemailer provider sends the sign-in email through any SMTP server, including Nuntly's SMTP relay, with no send function to write. Auth.js does not ship nodemailer, and the latest nodemailer major is outside its peer range, so pin it. On v5 (peer range ^7.0.7 || ^8.0.5):
npm install nodemailer@8
Put the connection in one variable. The username is nuntly and the password is your API key:
EMAIL_SERVER=smtp://nuntly:ntly_your_api_key@smtp.nuntly.com:587EMAIL_FROM=Acme <auth@acme.com>
On port 587, Nodemailer upgrades the connection with STARTTLS before it authenticates.
In v5, register the provider:
// auth.tsimport NextAuth from 'next-auth';import Nodemailer from 'next-auth/providers/nodemailer';import { PrismaAdapter } from '@auth/prisma-adapter';import { prisma } from '@/lib/prisma';export const { handlers, auth, signIn, signOut } = NextAuth({adapter: PrismaAdapter(prisma),providers: [Nodemailer({server: process.env.EMAIL_SERVER,from: process.env.EMAIL_FROM,}),],});
In v4, install nodemailer@7 (the peer range of next-auth@4.24.15 is ^7.0.7) and pass the same server and from options to EmailProvider from next-auth/providers/email. The provider id is nodemailer in v5 and email in v4.
The SMTP route keeps Auth.js's default email template. The SDK route gives you control of the content and throws typed errors:
| Route | Code to write | What you control |
|---|---|---|
| SDK (custom HTTP provider) | One send function | Subject, HTML and text, error handling |
| SMTP (Nodemailer, default template) | None | Server and sender address; Auth.js renders the email |
When the sign-in email does not arrive
A failed send stops the sign-in. Auth.js v5 redirects the user to /api/auth/error?error=Configuration and logs the cause on the server under [auth][error]. NextAuth v4 redirects to /api/auth/error?error=EmailSignin and logs it under [next-auth][error][SIGNIN_EMAIL_ERROR]. Check that log first. An API error carries an HTTP status and a code, and an SMTP failure carries the SMTP reply code:
| Status | Code | Fix |
|---|---|---|
400 | domain_not_verified | Finish DNS verification for the from domain |
404 | domain_not_found | Add the from domain to your account |
535 (SMTP) | EAUTH | Check the API key in EMAIL_SERVER |
If the send succeeded and the email is still missing, open it in the Nuntly dashboard: its status shows whether it was delivered, bounced or rejected.
Migrate the NextAuth email provider to Better Auth
The Auth.js email provider maps to the Better Auth magicLink plugin. Auth.js has been maintained by the Better Auth team since September 2025 (Better Auth announcement, read 2026-11-14), which keeps addressing security patches and urgent issues. The Auth.js migration guide (read 2026-11-14) says:
If your current setup is working well, there's no urgent need to migrate.
When you do migrate, neither that guide nor the Better Auth migration guide covers the email provider. Here is how it maps:
| Auth.js | Better Auth | Note |
|---|---|---|
| Email provider | magicLink plugin | Add magicLinkClient on the client |
sendVerificationRequest | sendMagicLink | Receives email and url |
maxAge: 24 hours | expiresIn: 300 seconds | Set expiresIn to keep the old window |
VerificationToken table | Verification table | Stores value, not token |
The send function from Step 2 moves over unchanged. Only the field name differs, and expiresIn keeps the 24-hour window your users had:
// lib/auth.tsimport { betterAuth } from 'better-auth';import { magicLink } from 'better-auth/plugins';import { sendSignInEmail } from '@/lib/send-sign-in-email';export const auth = betterAuth({plugins: [magicLink({expiresIn: 60 * 60 * 24,sendMagicLink: ({ email, url }) => sendSignInEmail({ identifier: email, url }),}),],});
On the client, signIn.magicLink({ email }) replaces signIn('nuntly', ...). The magic link plugin documentation (read 2026-11-14) lists its other options.
Better Auth also sends emails Auth.js never did: email verification, password reset and, with the email OTP plugin, one-time codes. Each has its own callback. The Better Auth email how-to wires all of them to one send function. To configure every Better Auth email in one place, see Better Email.
Before you launch
Check these four points before real users sign in:
- The
fromaddress is on a domain verified in Nuntly. - Your
auth.tshas a database adapter, so Auth.js can store the verification token. - On v4,
nodemailer@7is installed, even with the SDK route. - A sign-in from an address outside your team arrives, and its link signs you in.
The SMTP route is the shortest path: no code, and Auth.js keeps rendering its default email. Use the SDK route when you want your own content and typed errors. The same sendSignInEmail function then carries over to Better Auth's sendMagicLink when you migrate. The NextAuth page in the docs keeps the settings for both versions in one table. Already on Better Auth or Supabase? The Better Auth email how-to and the Supabase email guide send their auth emails through Nuntly.
Ship emails, not infrastructure
Free plan available. No credit card required.
Start for free