Skip to content

Documentation

Send Better Auth emails through Mailtruss.

Better Auth works with any provider: give it a function that sends, and it calls it.

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.

Install

Add the client library next to Better Auth.

Terminal
npm install mailtruss

The two callbacks

Better Auth calls sendVerificationEmail and sendResetPassword with the user and a ready-made link. Its documentation advises against awaiting the send, so the response time does not reveal whether an account exists, and says to use waitUntil or similar on serverless platforms. This example sends without awaiting and logs a failure.

lib/auth.ts
import { betterAuth } from "better-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)};`);
const FROM = "Acme <hello@yourdomain.com>";
​
function send(to: string, subject: string, url: string, line: string) {
// Not awaited, so the timing of the response does not depend on the send.
// On a serverless platform, pass this promise to waitUntil() so it is not cut off.
return mail.emails.send({
from: FROM, to, subject,
html: `<p>${line}</p><p><a href="${escapeHtml(url)}">Continue</a></p>`,
text: `${line} ${url}`,
}).catch((e) => console.error("mail failed", e));
}
​
export const auth = betterAuth({
emailAndPassword: {
enabled: true,
requireEmailVerification: true,
sendResetPassword: async ({ user, url }) => { void send(user.email, "Reset your password", url, "Reset your password:"); },
},
emailVerification: {
sendOnSignUp: true,
sendVerificationEmail: async ({ user, url }) => { void send(user.email, "Verify your email address", url, "Confirm your email address:"); },
},
});

Try it without sending real mail

Sign up through your app with an address at your own domain, or temporarily change the to above to delivered@mailtruss.test, which needs no verified domain and reaches no real mailbox. Then open the message under Emails in the dashboard.

Terminal
curl -s https://mailtruss.com/api/v1/emails?limit=1 -H "Authorization: Bearer $MAILTRUSS_API_KEY"

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.

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