A snapshot of packages/ in the Weft repository; the official packages are published from these commits. Markup-Kit-Commit: dd1e6eb5270e62e0c8b6c202b3d01f0da6e00ddc
132 lines
5.1 KiB
Markdown
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.
|