Watch
1
0
Fork
You've already forked packages
0
packages/email/README.md
Weft packages 306b143104 packages/ at markup-kit dd1e6eb5270e
A snapshot of packages/ in the Weft repository; the official packages are published from these commits.

Markup-Kit-Commit: dd1e6eb5270e62e0c8b6c202b3d01f0da6e00ddc
2026-11-19 20:43:26 +00:00

5.1 KiB

@weft/email

Email for Weft: sending through Resend and Postmark, MIME messages with attachments, and templates that render to HTML and text. Its only capabilities are http.fetch@api.resend.com, http.fetch@api.postmarkapp.com and http.media, because its Img component shows the image a template names.

weft add weft/email
import { send } from "@weft/email"
import { resend } from "@weft/email/resend"
import { document } from "@weft/email/template"
import { render } from "std/app"
import { env } from "std/process"
import Receipt from "./Receipt"

let mail = resend({ apiKey: env("RESEND_API_KEY")! })

let body = document(render(Receipt, { name: "Ana", total: "19,99 €" }), {
  title: "Your receipt",
  preheader: "Thanks for your order",
  footer: "Example d.o.o., Ljubljana",
})
let sent = try await send(mail, {
  from: { email: "info@example.com", name: "Example" },
  to: ["ana@example.com"],
  subject: "Your receipt",
  html: body.html,
  text: body.text,
})
import Button from "@weft/email/components/Button"
import Facts from "@weft/email/components/Facts"
import H1 from "@weft/email/components/H1"
import P from "@weft/email/components/P"
import Strong from "@weft/email/components/Strong"

prop name: string
prop total: string
---
<H1>Thank you!</H1>
<P>Hi <Strong>{name}</Strong>, your payment came through.</P>
<Facts rows={[["Total", total]]} />
<Button url="https://example.com/orders" label="Your orders" />

Modules

module what
@weft/email Message, send, validate, allowlist, memory and outbox for tests
@weft/email/resend resend({ apiKey })
@weft/email/postmark postmark({ serverToken, messageStream? })
@weft/email/mime toMime(message), the message as RFC 5322 text
@weft/email/template document, isSafeUrl
@weft/email/components/… H1, H2, P, Strong, Em, A, Img, Ul, Ol, Facts, Button, Hr

Messages

send validates a message before anything leaves. A line break in a subject, a display name or a header is refused, because it would let whoever typed that text add headers of their own, such as a Bcc.

try await send(mail, {
  from: { email: "info@example.com", name: "Example" },
  to: ["ana@example.com"],
  replyTo: "owner@example.com",
  subject: "Your ticket",
  html: body.html,
  text: body.text,
  headers: [["List-Unsubscribe", "<https://example.com/unsubscribe?id=1>"]],
  attachments: [
    { filename: "ticket.pdf", content: pdf, type: "application/pdf" },
    { filename: "logo.png", content: logo, type: "image/png", contentId: "logo" },   // <img src="cid:logo">
  ],
})

Errors are values

EmailError what to do
InvalidMessage { field, message } fix the message: nothing was attempted
Rejected { status, code, message } a bad key, an unverified domain, a suppressed address: sending it again won't help
RateLimited { message, retryAfter } try again later
ProviderFailure { status, message } try again later
ConnectionFailed { message } the message may have been sent
BadResponse { message } the message may have been sent

Nothing is retried for you, because sending an email twice is worse than a delay. With Resend, idempotencyKey makes a repeat safe:

let mail = resend({ apiKey, idempotencyKey: m => `order-${orderId}` })

Staging

allowlist sends only to the addresses listed, and skips the rest without failing, so a staging site can't email real customers. "*" lifts the limit:

let mail = allowlist(resend({ apiKey }), (env("EMAIL_ALLOWLIST") ?? "info@example.com").split(","))

In tests, memory() keeps messages in outbox() instead of sending them.

Templates

A template is a Weft component. render from std/app turns it into HTML with inline styles and a text version that reads as if a person wrote it. Everything a component shows is escaped, and a link that isn't http, https, mailto, tel or cid keeps only its text. Your own markup works too: classes become inline styles, and hover:, dark: and breakpoint classes are left out.

document wraps a rendered template in the whole email, a centred column that works in mail clients.

What has and hasn't been tested

node packages/email/scripts/integration.mjs sends through both providers' APIs to a scripted server, and checks a full message with Python's email parser, an independent reader of the MIME. weft test tests/email.test.weft covers validation, encoding, payloads and templates. No email has been sent through Resend or Postmark themselves: the payloads follow their API references, so try a test key before relying on this.

Limits

  • No SMTP. std has no TCP or TLS sockets, so this package can't talk to a mail server. toMime already writes what SMTP's DATA needs, so only the socket is missing.
  • It reaches only Resend's and Postmark's API hosts. As a dependency, a baseUrl on any other host fails with a CapabilityError. To point it at a test server, the app lists that host in allow too, beside the two API hosts.