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

132 lines
5.1 KiB
Markdown

# @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.
```sh
weft add weft/email
```
```weft
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,
})
```
```weft file=Receipt.weft
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`.
```weft
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:
```weft
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:
```weft
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.