Mail

Transactional email as data. One template renders an HTML part and a plain-text part, every string is an i18n key, every colour is a design token, and delivery is a job. Package: @ultimat3/mail (tier 4) — the full reference is packages/mail/README.md.

import { blocks, defineMail, send, t } from '@ultimat3/mail';

export const receiptMail = defineMail({
  id: 'receipt',
  subject: 'mail.receipt.subject',            // an i18n key, never a literal
  input: t.object({ name: t.string, url: t.url }),
  template: ({ data }) => [
    blocks.heading('mail.receipt.heading', { name: data.name }),
    blocks.paragraph('mail.receipt.body'),
    blocks.button('mail.receipt.cta', data.url),
  ],
});

await send(receiptMail, { name: user.name, url }, { to: user.email, locale: ctx.locale });

send validates the data through the mail's schema, renders, and enqueues mail.send through the jobs facade, so inside a transaction the job commits or rolls back with it. It delivers inline only with { sync: true } or when no job driver is configured.

Rules

Which driver a boot installs

selectMailDriver(env) is the one answer; x dev and every role call it. The app does not change between environments — the credential does.

Every key, with what it means: Configuration → mail. More than one of SMTP_URL, RESEND_API_KEY and SES_REGION is X_CONFIG_INVALID rather than a silent winner. mail: in export const runtime = { … } (apps/<app>/runtime.ts) is the one seam for an app that builds its own — the mail adapter port: MailDriver from @ultimat3/mail/adapter, memoryMailDriver to copy, behavesLike(mailDriverConformance, () => yourDriver()) to prove it (Adapters). There is no setMailDriver (31.0.0); a test swaps one for itself with await swapAdapter('mail', driver) from @ultimat3/testing.

Keeping the sent bytes: mail.retainMime

Off by default; SMTP and SES only. As of 2026-10. The transports that build the MIME can keep the exact bytes they handed the provider, on SendResult.mime.

// app.config.ts
mail: { retainMime: { maxBytes: 262_144 } },

A throwing onRetained is logged (mail.retain_mime.failed) and does not fail the send.

Delivery events: @ultimat3/mail/events

A subpath, never the barrel: only a webhook route needs it, and every serving role loads @ultimat3/mail to send. One receiver per provider; each verifies the request, then normalises it to DeliveryEvent — delivered · bounced (bounce: 'hard' | 'soft') · complained · delayed, with messageId (the sending driver's SendResult.id), recipient, at, eventId and raw. One event per recipient; (eventId, recipient) is the dedupe key.

import { resendEventReceiver, sesEventReceiver } from '@ultimat3/mail/events';

export const ses = sesEventReceiver({ topicArns: [Bun.env['SES_EVENTS_TOPIC_ARN'] ?? ''] });
export const resend = resendEventReceiver({ secret: Bun.env['RESEND_WEBHOOK_SECRET'] ?? '' });
// const outcome = await ses.receive(request);  // { type: 'events' | 'ignored' | 'subscription', … }

Mount a receiver through webhookReceiver() (Jobs and workflows), the one door for an inbound webhook. Its verify calls ses.receive(inbound.request()) — a fresh Request over the exact bytes, verified there — and returns { eventId, payload } with the events as the payload (the SNS MessageId as the id), or { answer: Response } for a subscription confirm. Its handle applies the stored events in the worker without verifying again, so a retry an hour later is not refused by the signature window. Declaring it is its registration: the boot mounts its route. api/ holds no route file. SES_CONFIGURATION_SET names the SES configuration set sent on every message (ConfigurationSetName) — the set whose event destination publishes to that SNS topic.

Previews

As of 2026-11-06. defineMail({ preview }) declares the data a template is checked by: a value, parsed by input where it is written (X_MAIL_PREVIEW_INVALID), or (locale) => data, parsed at each render. Never production rows. x mail preview <id> [--locale <tag>] [--tz <zone>] [--out <dir>] [--json] renders it per locale with nothing sent, naming every key a locale lacks; x verify's i18n step renders every declared preview in every locale, so a preview is also a test. previewMail(id, { locale }) is the same render for a host. A mail with none: X_MAIL_PREVIEW_MISSING.

The /_x mail panel lists every registered mail beside the caught ones (templates): each declared preview rendered in each of the app's locales, dates in UTC, with the keys a locale lacks as templateGaps and a preview its schema refuses shown as that refusal. A mail with no preview is listed with hasPreview: false. ?template=<id> selects one; x dev's panel and its --json payload are the same facts.

No framework mails

Rule: @ultimat3/mail registers no mail. As of 31.0.0. Every mail an app sends is its own defineMail(), with its mail.<id>.* keys in the app's catalog; the base catalog carries mail.footer.* only. registeredMails() lists what the app declared; renderMessage() renders one without sending.

The six v30 mails (welcome, verify-email, reset-password, invite, mfa-enrolled, security-alert, FRAMEWORK_MAILS) are deleted: Upgrading entry 54.

Errors

Every X_MAIL_* code is in Error codes. The two an app meets first: X_MAIL_LOCALE_MISSING (pass locale: ctx.locale) and X_MAIL_CREDENTIAL_MISSING (set SMTP_URL, RESEND_API_KEY, or SES_REGION with its key pair — and MAIL_FROM — in the deployment).

Related: Notify fans one event out to mail, the in-app inbox and your own channels; Configuration lists the env vars.