Functional Weave
Code in Python

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 nothing
  • sendEmail(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 bcc
  • sendEmail(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>
messageEmailMessagewho it is to, the subject, and a text body, an HTML body or both
returnsSentEmailwhich 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";
impl/typescript.ts · 43 lines · open · raw
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.

ProviderWhat it is
resendResend's HTTP API (resend.com)
smtpAny SMTP server: implicit TLS on 465, STARTTLS on 587, AUTH PLAIN
logWrites each message to the log instead of sending it: development, previews and tests
VariableKindNeededRead byWhat it is
EMAIL_PROVIDERconfig · picks the providerrequiredevery providerwhich provider sends: resend, smtp or log
EMAIL_FROMconfigoptionalevery providerthe From address when a message names none, like Acme <hello@acme.example>
RESEND_API_KEYsecretrequiredresend onlyan API key from resend.com/api-keys, re_...
SMTP_URLsecretrequiredsmtp onlysmtps://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
Download for TypeScript email.send-1.0.0-typescript.fune · 28,846 bytes sha256 95ad7ed6fc82e051cb3557cc35e1d920ac9ed2a592c61eb60f37b8b5bb36430e

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.

CaseArgumentsExpected
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
CaseArgumentsExpected
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

PathBytes
README.md1,434
adapters/typescript/log.ts893
adapters/typescript/resend.ts1,755
adapters/typescript/smtp.ts6,009
contracts.json10,400
impl/typescript.ts2,114