Better Auth

Better Auth calls a function of yours every time it needs to send email. The integration is that function — there is no adapter, plugin, or intermediate configuration.

This is what we do with ourselves. The Kourio dashboard authenticates with Better Auth, and its reset and verification emails leave through our own transport. This guide is our production code with the names changed.

Install

npm install @kourio/sdk better-auth

pnpm add @kourio/sdk better-auth

yarn add @kourio/sdk better-auth

.env

KOURIO_API_KEY=kou_live_...

The key allows sending on behalf of every domain you have verified. It lives on the server, never in code that reaches the browser.

The minimum that works

auth.ts

import { betterAuth } from 'better-auth';
import { Kourio } from '@kourio/sdk';

const kourio = new Kourio(process.env.KOURIO_API_KEY!);
const FROM = 'Your Company <account@news.yourcompany.com>';

export const auth = betterAuth({
  emailAndPassword: {
    enabled: true,
    sendResetPassword: async ({ user, url }) => {
      await kourio.emails.send({
        from: FROM,
        to: user.email,
        subject: 'Reset your password',
        html: `<p>Click <a href="${url}">here</a> to reset your password. The link is valid for 1 hour.</p>`,
        text: `To reset your password, open: ${url}\n\nThe link is valid for 1 hour.`,
      });
    },
  },
  emailVerification: {
    sendOnSignUp: true,
    sendVerificationEmail: async ({ user, url }) => {
      await kourio.emails.send({
        from: FROM,
        to: user.email,
        subject: 'Confirm your email',
        html: `<p>Click <a href="${url}">here</a> to confirm your address.</p>`,
        text: `To confirm your address, open: ${url}`,
      });
    },
  },
});

One sender, in one place

After the third hook, the same block starts getting copied with a different comma. Worth extracting before that:

mailer.ts

import { Kourio } from '@kourio/sdk';

const kourio = new Kourio(process.env.KOURIO_API_KEY!);

export async function sendAuthEmail(input: {
  to: string;
  subject: string;
  html: string;
  text: string;
}) {
  try {
    await kourio.emails.send({
      from: 'Your Company <account@news.yourcompany.com>',
      to: input.to,
      subject: input.subject,
      html: input.html,
      text: input.text,
    });
  } catch (error) {
    /*
     * The failure is logged, not propagated.
     *
     * If the send takes down the response, the error message tells whoever asked whether that
     * address exists in your database — and that is how a "forgot password" form becomes a user
     * enumeration tool. Answer the same either way.
     */
    console.error('[auth] send failed', { subject: input.subject, error });
  }
}

Magic link

import { magicLink } from 'better-auth/plugins';

export const auth = betterAuth({
  plugins: [
    magicLink({
      sendMagicLink: async ({ email, url }) => {
        await sendAuthEmail({
          to: email,
          subject: 'Your sign-in link',
          html: `<p>Click <a href="${url}">here</a> to sign in. Valid for 5 minutes, single use.</p>`,
          text: `To sign in, open: ${url}\n\nValid for 5 minutes, single use.`,
        });
      },
    }),
  ],
});

A magic link is a password. State the expiry in the message and keep it short. A sign-in link valid for a week is a permanent password forgotten in an inbox.

One-time code (OTP)

import { emailOTP } from 'better-auth/plugins';

export const auth = betterAuth({
  plugins: [
    emailOTP({
      sendVerificationOTP: async ({ email, otp, type }) => {
        const subject = type === 'sign-in' ? `${otp} is your sign-in code` : `${otp} is your code`;
        await sendAuthEmail({
          to: email,
          subject,
          html: `<p style="font-size:28px;font-weight:600;letter-spacing:4px">${otp}</p><p>Valid for 5 minutes.</p>`,
          text: `Your code: ${otp}\n\nValid for 5 minutes.`,
        });
      },
    }),
  ],
});

Put the code in the subject. Someone waiting for a code reads it in the notification without opening the message — and that is the difference between a few seconds and one more step in the middle of a sign-in.

Organization invitation

import { organization } from 'better-auth/plugins';

export const auth = betterAuth({
  plugins: [
    organization({
      sendInvitationEmail: async ({ email, inviter, organization: org, id }) => {
        const url = `https://app.yourcompany.com/accept-invite/${id}`;
        await sendAuthEmail({
          to: email,
          subject: `${inviter.user.name} invited you to ${org.name}`,
          html: `<p>${inviter.user.name} invited you to <strong>${org.name}</strong>.</p>
                 <p><a href="${url}">Accept invitation</a></p>`,
          text: `${inviter.user.name} invited you to ${org.name}.\n\nAccept at: ${url}`,
        });
      },
    }),
  ],
});

With a Kourio template

If you want your brand in the email without writing 2007-era HTML, publish a template in the dashboard and send only the variables. Subject and sender come from it:

await kourio.emails.send({
  templateId: 'reset-password',   // the slug you gave the template
  to: user.email,
  variables: { name: user.name ?? '', url },
});

Each template block is a contract: given that content, Kourio guarantees it renders correctly in Outlook, in dark mode, and at 600px wide. You write the text; the markup is our problem.

Three things that only show up in production

Send text alongside html — always

HTML-only mail scores worse with spam filters, and a password reset is exactly the one that cannot land in the wrong folder. The text field costs one line.

Do not let a send failure take down the response

If sendResetPassword throws, Better Auth propagates the error to whoever asked — and the difference between “sent” and “error” tells an attacker which addresses exist in your database. Log the failure and answer the same either way.

Authentication is not marketing

Leave these sends as TRANSACTIONAL, which is the default. The class decides which reputation the message leaves under, and the two are measured apart precisely so a bad campaign cannot stop someone from getting into their own account.

When it does not arrive

Check that the domain is verified

No message leaves a domain without SPF, DKIM and DMARC published. See Domains.

Look the message up by address

GET /v1/emails?search=… brings the timeline: accepted, delivered, deferred, bounced. It is what answers “did it arrive?” without depending on your logs.

Check whether the address is suppressed

An address that hard-bounced stops receiving — transactional included. See Errors.

Sending

The two ways to compose a message, what counts against your quota, and why marketing takes a different path.

Get started

Send

Know what happened

Account

Integrations

Install

The minimum that works

One sender, in one place

Magic link

One-time code (OTP)

Organization invitation

With a Kourio template

Three things that only show up in production

When it does not arrive

Sending

​Install

​The minimum that works

​One sender, in one place

​Magic link

​One-time code (OTP)

​Organization invitation

​With a Kourio template

​Three things that only show up in production

​When it does not arrive

Sending

Install

The minimum that works

One sender, in one place

Magic link

One-time code (OTP)

Organization invitation

With a Kourio template

Three things that only show up in production

When it does not arrive