Repository navigation
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';
import { type Ctx } from '@ultimat3/core';
declare const user: { readonly id: string; readonly name: string; readonly email: string; readonly role: string };
declare const url: string;
declare const ctx: Ctx;
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.
| Rule | Why |
|---|---|
locale is required by the type |
a mail is read hours later; there is no ambient request locale. X_MAIL_LOCALE_MISSING backs it for JS callers |
| a text part is mandatory, derived from the blocks | HTML-only mail scores as spam and cannot be read by a screen reader; deriving it from blocks means the two parts cannot drift (X_MAIL_TEXT_MISSING) |
every string is a mail.<id>.<slot> key |
English ships in the package catalog; an app catalog overrides it — translating the framework mails is shipping keys, never editing a template |
| a mail with an unresolved key is not sent |
send() throws X_MAIL_KEY_MISSING before the transform and the queue, and it is terminal: a key the locale lacks, a catalog value still holding ⟦…⟧, or a {slot} with no value (meta.keys, meta.slots). A framework mail counts, so a locale that has not translated mail.* is refused. renderMessage() still returns the ⟦…⟧, because a preview should show it. A ⟦ from your data sends. x verify catches the app's own keys earlier: blocks.*, subject: (I18n). A framework template's keys live in the package, so no source scan reads them |
| every date takes an IANA zone |
options.tz, else ctx.tz, else UTC
|
| no CR/LF in a header-bound field | refused in rendering and again in the send job (X_MAIL_HEADER_INVALID), so every driver refuses the same message |
| one recipient rule, inline and queued |
to, cc, bcc, replyTo take the display form; a control character or a non-ASCII mailbox is X_MAIL_ADDRESS_INVALID at send(), whichever driver is installed |
unsubscribeUrl is one-click, and one-click is the supported path |
it emits List-Unsubscribe: <url> plus List-Unsubscribe-Post: List-Unsubscribe=One-Click (RFC 8058), and the footer links the same url. Serve it as ONE page: GET confirms and never unsubscribes (scanners prefetch), POST unsubscribes — defineRoute({ render: 'ssr', …, post: 'unsubscribe' }) binds the POST to an action with the url's query merged into its input (→ Routes). unsubscribeOneClick: false is the fallback for a url that cannot take a POST: the -Post line goes |
| sending is a job |
retry: { attempts: 5, backoff: 'exponential' }, and an idempotency key derived from the mail id and the rendered message, so a retry is one email |
selectMailDriver(env) is the one answer; x dev and every role call it. The app does not change
between environments — the credential does.
| env | driver |
|---|---|
nothing set, development / test
|
memoryMailDriver() — caught in the /_x mail panel, never sent |
nothing set, staging / production
|
unconfiguredMailDriver(...) — every send is X_MAIL_CREDENTIAL_MISSING; the boot still succeeds, so an app that sends no mail deploys |
SMTP_URL + MAIL_FROM
|
smtpMailDriver(...) — ESMTP over Bun.connect, STARTTLS required unless allowInsecure. MAIL_POOL_SIZE, MAIL_TIMEOUT_MS optional |
RESEND_API_KEY + MAIL_FROM
|
resendMailDriver(...) — one POST /emails with an Idempotency-Key
|
SES_REGION + SES_ACCESS_KEY_ID + SES_SECRET_ACCESS_KEY + MAIL_FROM
|
sesMailDriver(...) — one SES v2 SendEmail with the raw MIME, SigV4-signed, no SDK. SES_SESSION_TOKEN, SES_ENDPOINT, SES_CONFIGURATION_SET optional |
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.
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 } },| Rule | Detail |
|---|---|
true |
mail's default cap, DEFAULT_RETAIN_MIME_MAX_BYTES (256 KiB) |
| over the cap |
{ kind: 'digest-only', sha256, byteLength } — never a truncated message |
maxBytes |
a whole number above 0 (X_CONFIG_INVALID at defineConfig), at most RETAIN_MIME_CEILING_BYTES (10 MiB; X_CONFIG_INVALID at boot, judged before a transport is chosen) |
RESEND_API_KEY selected |
any retention refuses the boot: Resend builds the MIME on its own side |
| durable copy |
onRetained is code, not config — a queued send's result is not persisted. Build the driver with selectMailDriver(env, { retainMime: { onRetained } }) and hand its .driver to the mail runtime override (Configuration) |
A throwing onRetained is logged (mail.retain_mime.failed) and does not fail the send.
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', … }| Receiver | Verifies |
|---|---|
sesEventReceiver |
SNS: the topic is in topicArns, the certificate URL is https://sns.<topic region>.amazonaws.com/…pem, SignatureVersion 1 or 2, Timestamp within toleranceMs (1 h). A SubscriptionConfirmation returns its confirmUrl; it is fetched only with confirmSubscriptions: true
|
resendEventReceiver |
Svix: HMAC-SHA256 under the whsec_ secret, constant-time, within toleranceMs (5 min) |
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.
As of 2026-11-15. Rule: received email is inboundMail(), a factory over
webhookReceiver() — never a ninth primitive, never a route
file. Declared in defineApi({ jobs }), the boot mounts its POST path.
import { inboundMail, resendInbound } from '@ultimat3/mail/inbound';
export const supportInbox = inboundMail({
name: 'support.inbound',
path: '/hooks/mail/inbound',
// A thunk, built on the first delivery: every role imports this, only the web role receives.
provider: () =>
resendInbound({
secret: Bun.env['RESEND_INBOUND_SECRET'] ?? '',
apiKey: Bun.env['RESEND_API_KEY'] ?? '',
}),
tenant: 'none',
handle: async ({ message }) => ({ subject: message.subject }),
});| Step | Where | What |
|---|---|---|
| verify | the door | the provider's signature over the exact bytes — before any parse. SNS via sesEventReceiver's verifier, Svix via resendEventReceiver's. A forgery is X_MAIL_EVENT_UNVERIFIED (401) and queues nothing |
| queue | the door | the verified envelope (recipients, and SES's content or Resend's email id), .sensitive()
|
| fetch | the job | SES: the row's content. Resend: GET /emails/receiving/:id with the API key, then the signed raw.download_url without it |
| parse | the job | in-tree, bounded MIME: multipart trees, base64 / quoted-printable, RFC 2047 words, RFC 2231 filenames, address groups |
| store | the job | each attachment through storage's validateUpload (size, allowlist, sniff) and put, at a key derived from the message id |
| handle | the job | your function, with one InboundMessage, at least once per eventId
|
| Bound | Default | Refusal |
|---|---|---|
limits.maxBytes |
10 MiB |
X_MAIL_INBOUND_TOO_LARGE (meta.limit) — refused whole, never truncated |
limits.maxParts · maxDepth
|
100 · 8 | the same |
limits.maxAttachments · maxHeaderBytes
|
20 · 64 KiB | the same |
| unreadable MIME | — |
X_MAIL_INBOUND_MALFORMED (meta.problem), terminal |
Sender-controlled, unsanitised: html, every filename, every contentId, subject, the
address names. Never render html on the app's origin (a sandboxed frame, or text); never use a
filename as a path. recipients comes from the provider's signed payload, never a header: SES's
is the SMTP envelope; Resend's is its to, not documented as the envelope — route only on your
own receiving domain. An SES virus verdict of FAIL stores no attachment (refusal: 'verdict')
unless attachments: { keepOnVirusFail: true }.
An attachment the upload policy refuses (HTML, SVG, a type the sniff contradicts) arrives
stored: false with storage's code — or X_MAIL_INBOUND_MALFORMED when its transfer encoding does
not decode; the message is still delivered (only an undecodable text or HTML BODY refuses it). attachments: { disk, policy, prefix } overrides each part; attachments: false stores nothing. SES's spam/virus/SPF/DKIM/DMARC
verdicts ride on message.verdicts — what to do about a FAIL is the app's decision.
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.
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.
| Where it comes from | |
|---|---|
| email verification, password reset |
@ultimat3/auth sends auth.email-verify / auth.password-reset through the app's MailSender, keys in the app catalog |
| welcome, invite, security alert, anything else | the app's own defineMail() — business convention, never shipped (axiom 8) |
The six v30 mails (welcome, verify-email, reset-password, invite, mfa-enrolled,
security-alert, FRAMEWORK_MAILS) are deleted: Upgrading entry 54.
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.
Ultimate — v31.48.0 As of 2026-10. The full-stack framework where the primary developer is an AI agent: bunx create-ultimate myapp → Getting started · live demo. MIT licensed. What npm serves is npm view @ultimat3/core version, never this line, and this footer is the only page that stamps a version.
Repository · Issues · Changelog · llms.txt
Edits to these pages are synced from wiki/ in the repository — change the file there, not the wiki, or the next sync overwrites it.
Start
- Getting started
- Installation
- Shapes
- Bare VM
- Project layout
- Migrating an existing app
- Compared to other stacks
Tutorials
- 1 · First app
- 2 · First feature
- 3 · Auth and admin
- 4 · Jobs and realtime
- 5 · Deploy free
- 6 · Growing up
Primitives
- The eight primitives
- Building your own base
- Actions
- Entities and migrations
- Policies and authz
- Queries and live queries
- Client data
- Jobs and workflows
- Scheduled tasks
- Routes and render modes
Capabilities
- Realtime
- Caching and invalidation
- Batching and preloading
- N+1 detection
- PWA and offline
- Client navigation
- MCP and AI
- Agents
- Working with many agents
- Admin dashboard
- Scraping
- Auth
- Notify
- Storage and uploads
- Feature flags
- SEO
- Static assets
Cross-cutting
- I18n
- Theming
- UI components
- Interface rules
- Timezones and dates
- Money
- Outbound HTTP
- Resource management
- Migrations and backfills
- Testing
- CI: the gate across parallel jobs
Reference