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.
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.
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_keyor401 missing_api_key: the key is wrong, revoked or not sent. Send it asAuthorization: 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 theRetry-Afterheader. 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.451or452: 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.