@ultimat3/mail

@ultimat3/mail ✉️

Transactional email as data. One template renders both 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.

import { defineMail, send, blocks, 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 data through the mail's schema, renders, then enqueues mail.send. It delivers inline only when { sync: true } is passed or no job driver is configured.

Rules

Rule	Why
locale is required by the type	a mail is read hours later; there is no ambient request locale to fall back to. X_MAIL_LOCALE_MISSING is the backstop for JS callers
Text part is mandatory	HTML-only mail scores as spam and is unreadable to screen readers. Empty text ⇒ X_MAIL_TEXT_MISSING
Text is derived from blocks	never scraped out of the HTML, so the two parts cannot drift
Every string is a key	mail.<id>.<slot>; English lives in src/catalog.ts and app catalogs override it
Every colour is a token	MAIL_TOKENS in layout.ts holds light + dark hexes; templates never see a hex
Every date takes an IANA zone	options.tz, else ctx.tz, else UTC
No CR/LF in a header-bound field	checked in renderMessage and again in sendMailJob, so every driver refuses the same message (X_MAIL_HEADER_INVALID). mime.ts keeps its own gate for the headers the SMTP transport mints itself
Sending is a job	retry: { attempts: 5, backoff: 'exponential' }, idempotency key derived from (mailId, recipients, hash(rendered)), or (mailId, your key) when you pass one — a caller's key is scoped to its mail so two templates cannot dedupe each other away

Drivers

setMailDriver(driver) once at boot. Asking for one that was never set is X_MAIL_DRIVER_UNAVAILABLE.

Driver	Use	Behaviour
createMemoryDriver({ clock? })	dev, tests	retains messages; outbox() / lastTo() feed the /_x mail panel, ordered by SentMail.at — pass a frozenClock() to choose it
createLogDriver()	workers without credentials	one structured line per message through core's logger; bodies never logged
createUnconfiguredDriver(env)	a deploy that configured no transport	refuses every send with X_MAIL_CREDENTIAL_MISSING; delivers nothing and claims nothing
createSmtpDriver({ url, from })	prod	real ESMTP over Bun.connect: STARTTLS, AUTH PLAIN/LOGIN, quoted-printable MIME
createResendDriver({ apiKey, from })	prod	one POST /emails, Idempotency-Key on every request

Which one a boot installs

selectMailDriver(env) is the one answer, and x dev and runRole both call it. Nothing about the app changes between environments; the credential does.

env	driver
(nothing set), development / test	createMemoryDriver() — caught, never sent
(nothing set), staging / production	createUnconfiguredDriver(...) — every send is X_MAIL_CREDENTIAL_MISSING
SMTP_URL + MAIL_FROM	createSmtpDriver(...), MAIL_POOL_SIZE optional
RESEND_API_KEY + MAIL_FROM	createResendDriver(...)

No credential outside development is a refusal, not the embedded default. The memory driver there answered accepted for mail that never left the process — password resets, receipts and invitations all reported as sent, none delivered, no error anywhere. The refusal lands on the send, not on the boot, so an app that sends no mail still deploys. Which environment this is comes from core's isLocal() (ULTIMATE_ENV, else NODE_ENV, else development) — mail does not own a second reading of it.

Both credentials at once is X_CONFIG_INVALID rather than a winner picked for you, and a transport with no MAIL_FROM is refused at boot instead of on the first send. A host that is not x dev calls selectMailDriver itself, or constructs a driver directly — setMailDriver is the only seam either way.

SMTP

smtps://user:pass@host:465 is implicit TLS; smtp://host:587 starts in the clear and upgrades with STARTTLS. Credentials are percent-decoded, so a password with @ or / works.

Rule	Why
A server offering no STARTTLS is refused	the message and the password would cross in the clear. allowInsecure: true is the explicit opt-out
Capabilities are re-read after STARTTLS	most servers only advertise AUTH once encrypted, and a cleartext EHLO can be stripped in flight
Any rejected recipient fails the send	delivering to three of four addresses and reporting success is the one outcome a caller cannot detect
poolSize (default 4) caps concurrent connections	a burst of sends queues instead of opening one socket each
Bcc never reaches a header	it travels in RCPT TO only
Every envelope address is gated for CR/LF	MAIL FROM/RCPT TO are built by interpolation, and bcc is the one address no header check ever sees. Refused (X_MAIL_ADDRESS_INVALID), never stripped — a rewritten address delivers somewhere else
The reported id is the Message-ID	an SMTP 250 carries nothing a caller could correlate
The Message-ID is stable per message	SMTP has no idempotency protocol, so it is the one identifier a receiving mailbox can collapse a retry on. A fresh token per attempt made a timeout past DATA a second email. It is a one-way digest of mailIdempotencyKey, never the key: the key holds the recipient list, and this header is visible to all of them

Resend

RESEND_API_KEY and a verified sending domain. Every request carries Idempotency-Key: mailIdempotencyKey(message) — a job retry after a timeout hands Resend the identical message, and that header is what makes it one email. 408/409/425/429 and 5xx are retryable (isRetryableStatus, @ultimat3/core); every other non-2xx is a configuration problem that retrying cannot fix.

Framework mails

Registered by importing them — the import IS the registration. FRAMEWORK_MAILS is the list, and registeredMails() / registeredMailIds() answer for an app's own mails as well. There is no x mail command; a host that wants to list or preview a mail calls those and renderMessage().

id	Input
welcome	{ name, appName, url }
verify-email	{ name, url, expiresMinutes }
reset-password	{ name, url, expiresMinutes }
invite	{ inviterName, orgName, url, expiresHours }
mfa-enrolled	{ name, method, at }
security-alert	{ name, event, ip, at }

Translating them = shipping mail.* keys in an app catalog. Never edit a template.

Errors

Code	Fix
X_MAIL_LOCALE_MISSING	send(mail, data, { to, locale: ctx.locale })
X_MAIL_TEMPLATE_UNKNOWN	export a defineMail({ id }) and import it (also raised for an unregistered layout)
X_MAIL_DUPLICATE	rename one of two defineMail({ id }) declarations
X_MAIL_TEXT_MISSING	add a text-bearing block to the template
X_MAIL_DRIVER_UNAVAILABLE	setMailDriver(createMemoryDriver()) at boot — a wiring bug
X_MAIL_CREDENTIAL_MISSING	set SMTP_URL (or RESEND_API_KEY) and MAIL_FROM in the deployment — an operations one
X_MAIL_HEADER_INVALID	strip CR/LF from the interpolated value before it reaches a header
X_MAIL_ADDRESS_INVALID	pass a bare addr-spec — an envelope address may hold no control character and no </>
X_MAIL_SEND_FAILED	the cause names the stage, the provider's status and whether a retry can help — and so does error.retry, which is what sendMailJob acts on: terminal dead-letters a 550 or a rejected credential at attempt 1 instead of sending it four more times

Commands

bun test packages/mail
bun run --filter @ultimat3/mail typecheck