email.send
Send a transactional email through Resend, any SMTP server or the log, behind one call.
Integration · does I/O It talks to resend, smtp or log, reads 2 secrets from the environment, and is tested by contract tests on recorded exchanges, offline. Providers and environment.
TypeScript only A Python or Rust project cannot use it.
1.0.0 · published 2026-10-09 by charlie · Anterra
Pinned by 17 contract tests on recorded exchanges, offline, run in TypeScript · per provider: resend 5, smtp 6, log 4.
What it does
Send one transactional email (a welcome, a password reset, a receipt) through whichever provider the environment chooses, with the same call everywhere:
import { sendEmail } from "#fune/email.send@^1";
await sendEmail({ to: ["ada@example.com"], subject: "Welcome", text: "Hello Ada" });
For example
sendEmail(to ada@example.com, subject Reset your password, text Hello Ada, Someone asked to reset your password. Follow https://acme.example/reset?t=abc123 within an hour, or ignore this e…)→ provider log, id log-000102030405 log: writes one line and sends nothingsendEmail(to Grace <grace@example.com>, cc team@acme.example, bcc audit@acme.example, from Support <support@acme.example>, subject Welcome, html <p>Welcome to <b>Acme</b>, Grace.</p>)→ provider log, id log-a1b2c3d4e5f6 log: an html-only message from its own sender, with cc and bccsendEmail(to grace@example.com, subject Welcome, text Welcome to Acme, Grace., html <p>Welcome to <b>Acme</b>, Grace.</p>, reply to help@acme.example)→ provider resend, id 49a3999c-0ce1-4ea6-ab68-afcd6dc2e794 resend: posts the message and returns Resend's id
The function
Implemented in TypeScript only.
TypeScript only. This capability has no Python implementation, so it is shown in TypeScript. A Python project cannot use it: fune build stops and names where it was required. Your choice of Python is kept for every other page.
export async function sendEmail(message: EmailMessage): Promise<SentEmail>
| message | EmailMessage | who it is to, the subject, and a text body, an HTML body or both |
| returns | SentEmail | which provider took it, and the id it gave the message |
The types it declares, generated into your project
/** One email. Addresses are name@example.com or Name <name@example.com>. */
export interface EmailMessage {
/** at least one recipient */
readonly to: readonly string[];
/** one line */
readonly subject: string;
/** the plain-text body */
readonly text?: string;
/** the HTML body; send text too, for mail clients that show no HTML */
readonly html?: string;
/** who it is from; EMAIL_FROM when left out */
readonly from?: string;
/** where replies go, when not to the sender */
readonly replyTo?: string;
readonly cc?: readonly string[];
readonly bcc?: readonly string[];
}
/** What the provider said when it took the message. */
export interface SentEmail {
/** resend, smtp or log */
readonly provider: string;
/** the provider's id: Resend's, the SMTP server's queue id, or the Message-ID it was sent with */
readonly id: string;
}
Your code names it in one line, in the file that uses it
import { sendEmail } from "#fune/email.send@^1";
import { chooseProvider, io } from "./funeio.ts";
import type { EmailMessage, SentEmail } from "./email_send_types.ts";
import { sendWithResend } from "./email_send_adapter_resend.ts";
import { sendWithSmtp } from "./email_send_adapter_smtp.ts";
import { sendWithLog } from "./email_send_adapter_log.ts";
const PROVIDERS = ["resend", "smtp", "log"];
// name@example.com, or Name <name@example.com>: one @, no spaces in the address.
const ADDRESS = /^(?:[^<>@]*<\s*[^\s<>@]+@[^\s<>@]+\.[^\s<>@]+\s*>|[^\s<>@]+@[^\s<>@]+\.[^\s<>@]+)$/;
function checkAddress(value: string, what: string): void {
if (typeof value !== "string" || !ADDRESS.test(value.trim())) {
throw new Error(`${what} ${JSON.stringify(value)} is not an email address`);
}
}
/**
* Send one email through the provider EMAIL_PROVIDER names. The message is
* checked before anything is sent, so a bad address or a missing body never
* reaches the provider; what the provider refuses is thrown with its reason.
*/
export async function sendEmail(message: EmailMessage): Promise<SentEmail> {
if (!message || !Array.isArray(message.to) || message.to.length === 0) {
throw new Error("an email needs at least one recipient in to");
}
for (const to of message.to) checkAddress(to, "to");
for (const cc of message.cc ?? []) checkAddress(cc, "cc");
for (const bcc of message.bcc ?? []) checkAddress(bcc, "bcc");
if (typeof message.subject !== "string" || /[\r\n]/.test(message.subject)) {
throw new Error("the subject is one line of text");
}
if (!message.text && !message.html) throw new Error("an email needs a text or an html body");
const from = message.from ?? io().env("EMAIL_FROM");
if (!from) throw new Error("no From address: give message.from, or set EMAIL_FROM");
checkAddress(from, "from");
if (message.replyTo !== undefined) checkAddress(message.replyTo, "replyTo");
const provider = chooseProvider("EMAIL_PROVIDER", PROVIDERS);
if (provider === "resend") return sendWithResend(message, from);
if (provider === "smtp") return sendWithSmtp(message, from);
return sendWithLog(message, from);
}Providers and environment
An integration is one interface with a provider behind it for each service it can use; each provider is an adapter file in the package. EMAIL_PROVIDER picks the provider at run time. Its code reaches the outside only through funeio, which fune build writes beside it. Values are never part of a package: set them in the environment.
| Provider | What it is |
|---|---|
| resend | Resend's HTTP API (resend.com) |
| smtp | Any SMTP server: implicit TLS on 465, STARTTLS on 587, AUTH PLAIN |
| log | Writes each message to the log instead of sending it: development, previews and tests |
| Variable | Kind | Needed | Read by | What it is |
|---|---|---|---|---|
| EMAIL_PROVIDER | config · picks the provider | required | every provider | which provider sends: resend, smtp or log |
| EMAIL_FROM | config | optional | every provider | the From address when a message names none, like Acme <hello@acme.example> |
| RESEND_API_KEY | secret | required | resend only | an API key from resend.com/api-keys, re_... |
| SMTP_URL | secret | required | smtp only | smtps://user:password@host:465 or smtp://user:password@host:587, percent-encoded |
Install
fune build
With that line in your source, in a TypeScript project (language typescript in fune.project), fune build resolves it and its 3 dependencies, pins them in fune.lock, downloads only the TypeScript package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. Or pin a range in fune.project and build in one step:
fune add email.send
An integration reads its settings and secrets from the environment. fune build writes every variable it reads, with what each is, to .fune/build/.env.example; fune secrets says which are set (never their values), and fune secrets --check fails a deploy step when one is missing.
fune secrets --check
The manifest, vectors and README with only the TypeScript implementation. Install it without the registry with fune add ./email.send-1.0.0-typescript.fune, or fetch it from a terminal with fune pull email.send@1.0.0:typescript.
It is TypeScript only, so there is no package for Python or Rust. The full package is one file too: email.send-1.0.0.fune, 28,818 bytes, sha256 e1a8ecb2fe75b301d5785f5efb6eea9ed0797e573f2d1d603690c4a8b7a0a48d.
Customise it in your app
The seams this capability offers. Put a marker directly above a function of your own and fune build wires it into the built code; the package on the registry is not changed, the built file’s header lists it under CUSTOMISED, and fune hooks lists every hook in the project. How hooks work.
before — your function gets the arguments and returns them, changed or not, or throws to refuse the call.
// fune: before email.send
after — your function gets the result and the arguments, and returns the final result.
// fune: after email.send
replace — inside this capability’s code only, calls to a dependency go to your function, with the same signature. Other capabilities that use it are unaffected; write in * to replace it everywhere.
// fune: replace encoding.base64 in email.send
// fune: replace encoding.hex in email.send
// fune: replace encoding.utf8 in email.send
step — your function runs at a numbered point inside the function’s body, receives the in-scope values it names as parameters, and may return replacements. List the points with fune show email.send --steps.
// fune: step email.send after <n|label>
Contract tests
These are contract tests on recorded exchanges, offline: each case runs the interface through one provider with fake credentials and a fixed clock, and the funeio seam serves the HTTP exchanges or socket dialogue it recorded. A request that differs from the recording, or a recorded exchange never made, fails the case. They prove the integration speaks the protocol as recorded and handles what the service answers; they do not reach the service. Every function needs at least 8, every provider at least 2, and every function that does I/O a case through each provider. fune verify runs them in a project, and the registry ran them in its sandbox, which has no network. Cases per provider: resend 5, smtp 6, log 4. The exact JSON is contracts.json.
| Case | Arguments | Expected | |
|---|---|---|---|
| log log: writes one line and sends nothing | to ada@example.com, subject Reset your password, text Hello Ada, Someone asked to reset your password. Follow https://acme.example/reset?t=abc123 within an hour, or ignore this e… | → | provider log, id log-000102030405 |
| log log: an html-only message from its own sender, with cc and bcc | to Grace <grace@example.com>, cc team@acme.example, bcc audit@acme.example, from Support <support@acme.example>, subject Welcome, html <p>Welcome to <b>Acme</b>, Grace.</p> | → | provider log, id log-a1b2c3d4e5f6 |
| resend resend: posts the message and returns Resend's id | to grace@example.com, subject Welcome, text Welcome to Acme, Grace., html <p>Welcome to <b>Acme</b>, Grace.</p>, reply to help@acme.example | → | provider resend, id 49a3999c-0ce1-4ea6-ab68-afcd6dc2e794 |
| resend resend: a refused message is thrown with Resend's reason | to grace@example.com, from Acme <hello@unverified.example>, subject Welcome, text Welcome to Acme, Grace. | → | error: resend refused the email (422 validation_error): The unverified.example domain is not verified. |
| resend resend: a bad key says which variable to fix | to grace@example.com, subject Welcome, text Welcome to Acme, Grace. | → | error: resend refused RESEND_API_KEY (401): API key is invalid |
| resend resend: no key set | to grace@example.com, subject Welcome, text Welcome to Acme, Grace. | → | error: RESEND_API_KEY is not set |
| smtp smtp: implicit TLS on 465, one recipient, a text body | to ada@example.com, subject Reset your password, text Hello Ada, Someone asked to reset your password. Follow https://acme.example/reset?t=abc123 within an hour, or ignore this e… | → | provider smtp, id 4F9A2C |
| smtp smtp: STARTTLS on 587, text and html, cc and bcc, a non-ASCII subject | to Grace <grace@example.com>, cc team@acme.example, bcc audit@acme.example, subject Bienvenue, café ☕, text Welcome to Acme, Grace., html <p>Welcome to <b>Acme</b>, Grace.</p>, re… | → | provider smtp, id <000102030405060708090a0b0c0d0e0f@acme.example> |
| smtp smtp: a refused login is thrown with the server's reply | to ada@example.com, subject Hi, text Hi | → | error: smtp: AUTH PLAIN was answered 535 5.7.8 Authentication credentials invalid |
| smtp smtp: a server without STARTTLS on 587 is refused before the password is sent | to ada@example.com, subject Hi, text Hi | → | error: does not offer STARTTLS, and the password is never sent in the clear |
Show the other 7 tests
| Case | Arguments | Expected | |
|---|---|---|---|
| no provider chosen | to ada@example.com, subject Hi, text Hi | → | error: EMAIL_PROVIDER is not set; set it to one of resend, smtp, log |
| an unknown provider | to ada@example.com, subject Hi, text Hi | → | error: EMAIL_PROVIDER is "sendgrid"; set it to one of resend, smtp, log |
| log a recipient that is not an address is refused before sending | to ada at example dot com, subject Hi, text Hi | → | error: to "ada at example dot com" is not an email address |
| log no recipients | to , subject Hi, text Hi | → | error: an email needs at least one recipient |
| resend no body | to ada@example.com, subject Hi | → | error: an email needs a text or an html body |
| smtp no From address anywhere | to ada@example.com, subject Hi, text Hi | → | error: no From address: give message.from, or set EMAIL_FROM |
| smtp a subject with a line break is refused (header injection) | to ada@example.com, subject Hi Bcc: everyone@example.com, text Hi | → | error: the subject is one line of text |
Verification
Verified by the operator, not the sandbox 17 test vectors declared; none run by the registry.
Verified locally by the registry's operator, not by the sandbox. This version was published with FUNE_VERIFY_MODE=inline-dev (the operator's import of the first-party registry, or a development server): the server validated the package - its manifest, signatures, imports, safety lint and test rules - but the registry did not run its test vectors in its sandbox. The operator runs them with `fune verify --all` before importing.
Signed by the registry with key fw-9dc887227da47575 (ed25519), over its integrity and this report's digest. The full report · JSON
More from the author
`EMAIL_PROVIDER` picks the provider:
- **resend** posts to Resend's HTTP API with `RESEND_API_KEY`. - **smtp** talks to the server in `SMTP_URL`: `smtps://user:password@host:465` for implicit TLS, or `smtp://user:password@host:587`, which it upgrades with STARTTLS and refuses to use without it. The message is MIME, each body base64 in lines of 76, with a `Message-ID` on the sender's domain. - **log** sends nothing: it writes one line per message to the log, which is what development, preview deployments and an application's own tests want.
`EMAIL_FROM` is the From address when a message gives none.
The message is checked before anything is sent: at least one recipient, every address an address, a one-line subject, a text or an HTML body, and a From. What the provider refuses is thrown with its status and its own reason.
The contract tests replay Resend's documented responses (success, a validation error, a bad key) and complete SMTP dialogues (implicit TLS, STARTTLS, a refused login), offline. They are not a substitute for sending one real email from a staging environment before going live.
Files
| Path | Bytes |
|---|---|
| README.md | 1,434 |
| adapters/typescript/log.ts | 893 |
| adapters/typescript/resend.ts | 1,755 |
| adapters/typescript/smtp.ts | 6,009 |
| contracts.json | 10,400 |
| impl/typescript.ts | 2,114 |