| Filename | Latest commit message | Latest commit date |
|---|---|---|
A snapshot of packages/ in the Weft repository; the official packages are published from these commits. Markup-Kit-Commit: dd1e6eb5270e62e0c8b6c202b3d01f0da6e00ddc |
||
| .. | ||
| components | ||
| scripts | ||
| tests | ||
| email.weft | ||
| mime.weft | ||
| postmark.weft | ||
| README.md | ||
| resend.weft | ||
| template.weft | ||
| weft.toml | ||
@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.
stdhas no TCP or TLS sockets, so this package can't talk to a mail server.toMimealready writes what SMTP'sDATAneeds, so only the socket is missing. - It reaches only Resend's and Postmark's API hosts. As a dependency, a
baseUrlon any other host fails with aCapabilityError. To point it at a test server, the app lists that host inallowtoo, beside the two API hosts.