Skip to content

Documentation

Send Auth.js sign-in emails through Mailtruss.

Two ways to send the magic link: the Nodemailer provider over SMTP, or your own provider that calls the API.

Before you start

You need a verified sending domain (see Domains) and an API key (under API keys in the dashboard; it is shown once). Keep the key in an environment variable on your server, never in code that runs in a browser or an app.

What Auth.js needs first

Email sign-in stores a verification token, so Auth.js requires a database adapter. That is a requirement of the email provider, not of Mailtruss. Set up your adapter first, as Auth.js's own docs describe.

Option 1: the Nodemailer provider

Auth.js does not bundle nodemailer, so install it, then point the provider at the Mailtruss relay. The API key is the password and any username works.

auth.ts
import NextAuth from "next-auth";
import Nodemailer from "next-auth/providers/nodemailer";
​
export const { handlers, auth, signIn, signOut } = NextAuth({
// adapter: yourDatabaseAdapter, // required for email sign-in
providers: [
Nodemailer({
server: { host: "smtp.mailtruss.com", port: 587, auth: { user: "mailtruss", pass: process.env.MAILTRUSS_API_KEY } },
from: "Acme <login@yourdomain.com>",
}),
],
});

Option 2: a provider that calls the API

A custom email provider is an object with a sendVerificationRequest function. This one sends the link through the Mailtruss API, escapes the address, and throws if the send fails so Auth.js can show an error.

auth.ts
import NextAuth from "next-auth";
import { MailClient } from "mailtruss";
​
const mail = new MailClient({ apiKey: process.env.MAILTRUSS_API_KEY! });
const escapeHtml = (s: string) => s.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
​
export const { handlers, auth, signIn, signOut } = NextAuth({
providers: [
{
id: "mailtruss", name: "Email", type: "email", maxAge: 24 * 60 * 60,
async sendVerificationRequest({ identifier: email, url }) {
await mail.emails.send({
from: "Acme <login@yourdomain.com>", to: email, subject: "Sign in to Acme",
html: `<p>Click to sign in: <a href="${escapeHtml(url)}">Sign in</a></p>`,
text: `Sign in to Acme: ${url}`,
});
},
},
],
});

A note on Auth.js

Auth.js's documentation now says the project is part of Better Auth. If you are starting a new project, see the [Better Auth guide](/docs/guides/better-auth). Existing Auth.js apps keep working with either option above.

Try it without sending real mail

Send to delivered@mailtruss.test first. It works before any domain is verified and reaches no real mailbox, so you can check your code and see the recorded timeline. Then try bounced@mailtruss.test to see what a bounce looks like. All the test addresses are listed under Sending.

See what happened

Open the message under Emails in the dashboard: it shows the recorded timeline, what each event proves, and a diagnosis if something went wrong. Or fetch it with GET /api/v1/emails/:id/events. To be told as it happens, add a webhook.

If it fails

API requests answer with an error name and message. The common ones:

  • 403 invalid_api_key or 401 missing_api_key: the key is wrong, revoked or not sent. Send it as Authorization: Bearer ms_live_….
  • 403 domain_not_verified: the from address is on a domain that is not verified. Publish the DNS records and re-check.
  • 422 validation_error: fix the field the message names. Nothing was sent and no quota was used.
  • 429 rate_limit_exceeded: back off for the Retry-After header. See rate limits.

Over SMTP, the relay answers with a reply code:

  • 535: the API key is wrong or revoked. Fix the password.
  • 550: refused for good (unverified domain, suppressed recipient, invalid message). Do not retry; the reply says why.
  • 552: too large, or the monthly limit is reached.
  • 451 or 452: temporary (rate limit, daily limit, or a brief problem on our side). Retry later; mail servers do this automatically.

Problems that happen after a message is accepted (bounces, complaints) are explained under delivery errors.

Other guides

Last updated

Something wrong or unclear on this page?

Report an issue