Email and SMS

Better IAM never talks to a mail or SMS provider itself. Every message it needs to send (a verification link, a password reset, an invitation, a security notice, a reminder) is written to the outbox with a template name and a payload, in the same transaction as the change that caused it. A worker then hands each message to a callback you supply, authentication.sendEmail or authentication.sendSms, which renders it and sends it through your own provider, sender domain, and branding.

Use this page to wire up delivery, render the built-in templates, and look up every template name your callback can receive.

• Transactional. A rolled-back change sends nothing, and a committed change is never lost.
• Sealed at rest. The payload (which can hold a single-use token) is encrypted with the deployment secret while it waits, and erased once the message is delivered or abandoned.
• Outside the request. Your callback runs from the worker, after commit, so a slow provider never holds a write lock or delays a sign-in.
• At least once. A message can reach your callback more than once; deduplicate by message.id.

Setup

import { betterIam } from 'better-iam';
import { sqliteAdapter } from 'better-iam/adapter-sqlite';
import { renderDeliveryMessage } from 'better-iam/auth/templates';
import { mailer, sms } from './providers';

const origin = 'https://app.example.com';

export const iam = betterIam({
  database: sqliteAdapter({ filename: './iam.db' }),
  secret: process.env.BETTER_IAM_SECRET!,
  baseURL: origin,
  authentication: {
    async sendEmail(message) {
      const rendered = renderDeliveryMessage(message, {
        appName: 'Acme Cloud',
        links: {
          invitation: ({ kind, tenantId, token }) => `${origin}/join?kind=${kind}&tenant=${tenantId}&token=${token}`,
          passwordReset: ({ tenantId, token }) => `${origin}/reset?tenant=${tenantId}&token=${token}`,
          verifyEmail: ({ tenantId, token }) => `${origin}/verify?tenant=${tenantId}&token=${token}`,
          emailChange: ({ tenantId, token }) => `${origin}/email?tenant=${tenantId}&token=${token}`,
          magicLink: ({ tenantId, token, destination }) =>
            `${origin}/magic?tenant=${tenantId}&token=${token}&to=${encodeURIComponent(destination)}`,
          account: ({ tenantId }) => `${origin}/${tenantId}/account`,
        },
      });
      // Templates the renderer does not know (plugin templates, phone-verify, ...) return undefined.
      if (!rendered) throw new Error(`No renderer for ${message.template}`); // retried later
      await mailer.send({ to: message.to, idempotencyKey: message.id, ...rendered });
    },
    async sendSms(message) {
      // SMS templates are `code` (passwordless sign-in) and `phone-verify`; both carry a six-digit `token`.
      await sms.send({ to: message.to, body: `Your Acme code is ${message.payload.token}` });
    },
  },
});

import { iam } from './iam';

setInterval(async () => {
  const { delivered, failed, abandoned } = await iam.auth.dispatchOutbox();
  if (abandoned > 0) console.warn(`outbox: ${abandoned} message(s) abandoned`);
  await iam.events.dispatch(); // audit hooks and subscribers share the schedule
}, 60_000);

* * * * *  better-iam outbox --config better-iam.config.mjs

Usage

The delivery message

Your callback receives one DeliveryMessage:

Never log payload: several templates carry single-use tokens or codes that sign a person in.

Render the built-in templates

renderDeliveryMessage(message, { appName, links }) from better-iam/auth/templates turns a message into { subject, text, html } with HTML escaping, header-safe subjects, and a plain layout. The subpath has no native dependencies, so it also runs in email workers and edge runtimes. It is also exported from better-iam/auth and @better-iam/auth (not from the better-iam root).

import { renderDeliveryMessage, type TemplateLinks } from 'better-iam/auth/templates';

const links: TemplateLinks = {
  account: ({ tenantId, signInUrl }) => `${signInUrl ?? 'https://app.example.com'}/${tenantId}/account`,
};

const rendered = renderDeliveryMessage(
  { template: 'new-sign-in', to: 'alice@example.com', tenantId: 'ten_1', payload: { time: new Date().toISOString(), method: 'password' } },
  { appName: 'Acme Cloud', links },
);
// rendered?.subject, rendered?.text, rendered?.html

• appName (default 'Better IAM') names your product in subjects and the footer. It is a render option, not authentication.appName.
• A missing link builder falls back to showing the raw token or code, or to the account link for notices.
• Templates the renderer does not know return undefined; render those yourself (see the table below).
• describeUserAgent(userAgent) turns a User-Agent into a short phrase such as "Chrome on Windows". The built-in security notices use it so a crafted header never reaches a message verbatim; do the same in your own templates.

The links builders are:

Template reference

Every template name the server can queue. Rendered says whether renderDeliveryMessage knows it; for the others, build the message yourself from the payload.

Sign-in and account (from @better-iam/auth):

Organizations and members:

Access requests and governance (sent only when sendEmail is configured):

Feature notices (each feature's own settings decide whether it emails):

Plugins can queue their own template names (see Queue messages from a plugin). Your callback should throw, not silently drop, when it meets a template it cannot render, so the message stays in the outbox and doctor reports it.

Dispatch the outbox

iam.auth.dispatchOutbox(limit?) delivers up to limit due messages (default 100, 1 to 1000), oldest first, and returns { delivered, failed, abandoned }.

• Each message is claimed in its own short transaction with a 60-second lease, so several workers can run at once without sending the same message twice in parallel.
• A failed attempt waits 30 s × 2^(attempts − 1), capped at one hour, before the next one.
• After authentication.maxDeliveryAttempts failed attempts (default 25, about 18 hours of retries) the message is abandoned with failedAt and lastError (the error name and message, at most 256 characters).
• Webhook deliveries travel through the same outbox; see webhooks.

Queue messages from a plugin

A plugin endpoint handler receives deliver, which queues an email or SMS in the endpoint's transaction through the same outbox and callbacks, and returns the message ID.

import { IamError, type IamPlugin } from 'better-iam/core';

export const reports: IamPlugin = {
  id: 'reports',
  actions: ['reports:share'],
  endpoints: [
    {
      method: 'POST',
      path: 'share',
      action: 'reports:share',
      validate(value) {
        const input = value as { tenantId?: unknown; email?: unknown; reportId?: unknown } | null;
        if (!input || typeof input.email !== 'string' || typeof input.reportId !== 'string')
          throw new IamError('INVALID_INPUT', 'email and reportId required');
        return { tenantId: input.tenantId, email: input.email, reportId: input.reportId };
      },
      async handler({ deliver }, input) {
        const messageId = await deliver({
          kind: 'email',
          to: String(input.email),
          template: 'report-shared', // your own template name; render it in sendEmail
          payload: { reportId: String(input.reportId) },
        });
        return { messageId };
      },
    },
  ],
};

deliver fails with FEATURE_DISABLED when the deployment has no callback for that kind, which rolls back the endpoint's transaction. See extensions.

Options

All delivery options live under authentication in the server options.

Construction fails with INVALID_CONFIG when requireEmailVerification, passwordlessEmail, or failedSignInAlerts is set without sendEmail, or passwordlessSms without sendSms. Related settings: observability.metrics.gauges adds the better_iam_outbox_messages{state} gauge, and iam.sweepExpired() deletes delivered and abandoned messages after deliveryRetentionMs (30 days by default).

Schema

Messages are stored in the outbox collection (type OutboxMessage from better-iam/core):

Errors

doctor reports outbox-stalled when messages have waited more than 15 minutes and outbox-abandoned for messages abandoned in the last day.

Next steps