Mail plugin

npm install @orthacms/mail-server @orthacms/mail-provider-smtp

# .env
# "smtp" (or "console" in the reference server). Unset = send nothing.
MAIL_PROVIDER=smtp
# required once MAIL_PROVIDER is set: every link is built from it
APP_URL=https://cms.example.com
# required once MAIL_PROVIDER is set
MAIL_FROM="Ortha CMS <no-reply@example.com>"
MAIL_REPLY_TO=support@example.com
# what the copy calls the product; default "Ortha CMS"
MAIL_PRODUCT_NAME=Acme CMS
# debugging only: also return the raw token from the API
MAIL_REVEAL_LINKS=false
# worker poll interval; 0 = queue here, send from another process
MAIL_DELIVERY_INTERVAL_MS=2000
MAIL_MAX_ATTEMPTS=5

# SMTP transport — see the SMTP page
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=apikey
SMTP_PASSWORD=...
SMTP_REQUIRE_TLS=true

import type { MailPluginConfig } from '@orthacms/mail-server';
import type { SmtpMailProviderOptions } from '@orthacms/mail-provider-smtp';

export interface OrthaCmsMailConfig extends MailPluginConfig {
    backend: 'smtp' | 'console';
    smtp?: SmtpMailProviderOptions;
}

export function mailConfig(): OrthaCmsMailConfig | undefined {
    const selected = backend(); // reads MAIL_PROVIDER; undefined when unset
    if (!selected) return undefined;

    return defined({
        backend: selected,
        appUrl: requireEnv('APP_URL', '…'),
        from: requireEnv('MAIL_FROM', '…'),
        replyTo: readEnv('MAIL_REPLY_TO'),
        productName: readEnv('MAIL_PRODUCT_NAME'),
        revealLinks: readFlag('MAIL_REVEAL_LINKS', false),
        deliveryIntervalMs: readOptionalPositiveInt('MAIL_DELIVERY_INTERVAL_MS'),
        maxAttempts: readOptionalPositiveInt('MAIL_MAX_ATTEMPTS'),
        smtp: when(selected === 'smtp', () => smtpTransport()) // SMTP_* — see the SMTP page
    });
}

// apps/server/src/plugins.ts
import { MailServerPlugin } from '@orthacms/mail-server';
import { createSmtpMailProvider } from '@orthacms/mail-provider-smtp';
import { createConsoleMailProvider } from '@orthacms/mail-provider-console';
import type { MailProvider } from '@orthacms/mail-domain';

export function mailProvider(config: OrthaCmsConfig): MailProvider | null {
    const mail = config.plugins.mail;
    if (!mail) return null;
    if (mail.backend === 'console') return createConsoleMailProvider();
    if (!mail.smtp) throw new Error('MAIL_PROVIDER=smtp but no SMTP settings — set SMTP_HOST.');
    return createSmtpMailProvider(mail.smtp);
}

function mailPlugin(config: OrthaCmsConfig): ServerPlugin[] {
    const provider = mailProvider(config);
    const mail = config.plugins.mail;
    return provider && mail ? [MailServerPlugin({ provider, config: mail })] : [];
}

// in the plugin list: after DatabasePlugin, before UsersPlugin (users queues through it)
[
    // …DatabasePlugin, IdentityPlugin, WorkspacesPlugin, ActivityPlugin
    ...mailPlugin(config),
    UsersPlugin()
    // …
];

LOG [MailProviderCheck] Mail is enabled through the "smtp" provider, sending as Ortha CMS <no-reply@example.com>.

Error: The mail provider "smtp" refused the configured sender "Ortha CMS <no-reply@example.com>": SMTP relay smtp.example.com:587 refused the connection — EAUTH: 535 …

curl -s -X POST -b cookies.txt http://localhost:3000/api/users/7d0c…/reveal-link

{
    "kind": "invite",
    "link": "https://cms.example.com/identity/accept-invite?token=8f14e45fceea167a",
    "queuedAt": "2026-09-30T09:14:00.000Z",
    "attempts": 3,
    "lastError": "ECONNECTION: connect ETIMEDOUT"
}

{
    "statusCode": 409,
    "error": "Conflict",
    "code": "NO_REVEALABLE_LINK",
    "message": "There is no undelivered message for this member; its link is not recoverable. Resend the invite or re-issue the reset instead: 7d0c…"
}

import { formatExpiry, type MailTemplate } from '@orthacms/mail-domain';

const invite: MailTemplate = (ctx) => ({
    subject: `Join the ${ctx.productName} editorial team`,
    text: [
        `Hi ${ctx.recipientName ?? 'there'},`,
        `${ctx.actorName ?? 'An editor'} added you to ${ctx.productName}.`,
        `Accept before ${formatExpiry(ctx.expiresAt)} (UTC):`,
        '',
        ctx.link
    ].join('\n')
});

MailServerPlugin({ provider, config: { ...config.plugins.mail, templates: { invite } } });

InviteMemberUseCase            inside uow.run
  ├─ member saved
  ├─ InviteTokenService.rotate()   plaintext exists only here
  ├─ mail_deliveries row           rendered message, link included
  └─ outbox: member.invited        audit event, no secret
       │ commit
MailDeliveryWorker             claims with FOR UPDATE SKIP LOCKED, commits the claim
  └─ MailProvider.send()        no transaction open

import {
    MailPermanentError,
    type MailMessage,
    type MailProvider,
    type MailReceipt
} from '@orthacms/mail-domain';

export function createAcmeMailProvider(options: { apiKey: string }): MailProvider {
    return {
        id: 'acme',                                   // stamped on every delivery row
        capabilities: { messageId: true, verifiable: true },

        async send(message: MailMessage): Promise<MailReceipt> {
            const response = await fetch('https://api.acme-mail.example/v1/send', {
                method: 'POST',
                headers: {
                    authorization: `Bearer ${options.apiKey}`,
                    'content-type': 'application/json'
                },
                body: JSON.stringify({
                    from: message.from,
                    to: message.to,
                    reply_to: message.replyTo,
                    subject: message.subject,
                    text: message.text,
                    html: message.html,
                    headers: message.headers   // includes X-Orthacms-Mail-Kind
                })
            });
            if (response.status >= 400 && response.status < 500 && response.status !== 429) {
                // Retrying will not help: stop the row now.
                throw new MailPermanentError(`Acme refused the message: ${response.status}`);
            }
            if (!response.ok) {
                throw new Error(`Acme is unavailable: ${response.status}`); // retried
            }
            const { id } = (await response.json()) as { id?: string };
            return { providerMessageId: id };
        },

        // Required when capabilities.verifiable is true. A throw refuses the boot.
        async verify(): Promise<void> {
            const response = await fetch('https://api.acme-mail.example/v1/me', {
                headers: { authorization: `Bearer ${options.apiKey}` }
            });
            if (!response.ok) throw new Error(`Acme rejected the API key: ${response.status}`);
        }
    };
}