@rivi-software/workers-mail 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RIVI Software
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,164 @@
-# Temporary Holding Version
+# @rivi-software/workers-mail
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Mail from Cloudflare Workers through [Amazon SES](https://aws.amazon.com/ses/) once a Worker holds SES's key, and through [Cloudflare Email Service](https://developers.cloudflare.com/email-service/)'s `send_email` binding until then and whenever SES refuses a message. One call, `sendMail(env, mail)`, picks the transport, formats the addresses and headers for it, and answers with the `Message-ID` the message went out with, so a reply threads back.
+
+The binding needs no keys and sends from the day a domain is onboarded; SES takes larger messages and list mail, but needs a verified identity, production access and an IAM key first. With both set up, mail keeps going while SES is not ready yet, and when SES refuses a message (an identity not verified yet, a policy that does not allow the address, a throttle) the binding sends it instead. SES goes through the [Email SDK](https://email-sdk.dev/docs/adapters/ses) (`@opencoredev/email-sdk`), which signs SES's API v2 requests with `fetch` and Web Crypto, so the Worker needs no AWS SDK.
+
+## Install
+
+```bash
+npm install @rivi-software/workers-mail
+```
+
+The Worker needs Node.js compatibility, since the Email SDK imports Node's `fs`, `os`, `path` and `crypto` modules: it is on by default from compatibility date 2026-08-04, and an earlier date needs the `nodejs_compat` flag, without which the Worker fails to start (`No such module "node:fs/promises"`). The package is ESM only, and runs in Node 22 and later as well, for tests.
+
+## Usage
+
+```jsonc
+// wrangler.jsonc
+{
+  // Node.js compatibility is on from this date; an earlier one needs "compatibility_flags": ["nodejs_compat"].
+  "compatibility_date": "2026-10-15",
+  // Cloudflare Email Service, for a domain onboarded to Email Sending.
+  "send_email": [{ "name": "EMAIL" }],
+  // Amazon SES: the region here, the key as two secrets (below).
+  "vars": { "SES_REGION": "eu-west-1" },
+}
+```
+
+```bash
+npx wrangler secret put SES_ACCESS_KEY_ID
+npx wrangler secret put SES_SECRET_ACCESS_KEY
+```
+
+```ts
+import { MailError, sendMail } from "@rivi-software/workers-mail";
+
+export default {
+  async fetch(request, env) {
+    try {
+      const sent = await sendMail(env, {
+        from: "Acme <no-reply@example.com>",
+        to: "jane@example.org",
+        subject: "Your sign-in link",
+        text: "Sign in: https://example.com/sign-in/…",
+        html: '<p><a href="https://example.com/sign-in/…">Sign in</a></p>',
+      });
+      // { transport: "ses" | "email-service", id, messageId: "<…>" }
+      return Response.json(sent);
+    } catch (err) {
+      if (!(err instanceof MailError)) throw err;
+      console.error(JSON.stringify({ event: "mail.failed", transport: err.transport, code: err.code }));
+      return new Response("Mail is unavailable", { status: 503 });
+    }
+  },
+} satisfies ExportedHandler<Env>;
+```
+
+`sendMail` reads these names from the object it is handed, the Worker's `env` as a rule:
+
+| Name | Kind | What |
+| --- | --- | --- |
+| `EMAIL` | `send_email` binding | Cloudflare Email Service. |
+| `SES_REGION` | var | The AWS region SES sends from, such as `eu-west-1`. |
+| `SES_ACCESS_KEY_ID`, `SES_SECRET_ACCESS_KEY` | secrets | The access key of an IAM user that may send ([below](#setting-up-ses)). |
+
+SES is used once all three SES values are set; until then, or with any of them empty, the binding. A Worker that binds other names hands them over itself: `sendMail({ EMAIL: env.MAILER, SES_REGION: env.AWS_REGION, … }, mail)`.
+
+## How it works
+
+`sendMail(env, mail)` sends through SES when `env` has its region and key, else through `env.EMAIL`. When SES answers with an error status, the binding sends the message instead. A refusal (4xx) means SES sent nothing. A server error (5xx) almost always means the same, but does not prove it, so in that rare case the message can arrive twice. `console.warn` then writes one line for the logs with SES's status and error type, never its message, which can name the recipient:
+
+```json
+{"event":"mail.ses_refused","status":403,"code":"AccessDeniedException"}
+```
+
+Without an answer from SES (the network, a timeout) the message may have gone out, so the error stands: sending it again through the binding could deliver it twice. Without the binding, SES's error stands too. What a transport refuses or fails at comes as a `MailError`, and so does a Worker with neither transport set up.
+
+What differs between the two transports, and what the package does about it:
+
+- **Message-ID.** Both write their own and take none from the sender. SES's is its `MessageId` at the region's sending domain, `<…@eu-west-1.amazonses.com>` (`<…@email.amazonses.com>` in us-east-1); the binding answers with its own. `SentMail.messageId` is that header either way, so a reply that names it in `In-Reply-To` threads back.
+- **Display names.** SES takes a name quoted, or MIME-encoded (RFC 2047) when it is not ASCII (`formatSesAddress`). Through the binding, recipients go as bare addresses, since the Email SDK's Cloudflare adapter refuses named ones, so their names are dropped there; the sender's and the Reply-To's stay.
+- **Headers.** SES takes a header of at most 996 characters, its name and value together, so a long thread's `References` is cut to the first message and the latest that fit, the way RFC 5537 (3.4.4) trims it (`fitReferences`). Email Service takes a value of up to 2,048 bytes, refuses a longer one with `E_HEADER_VALUE_TOO_LONG`, and takes only the headers on [its allowlist](https://developers.cloudflare.com/email-service/reference/headers/) and `X-` headers. The package hands the binding the headers as they are, so a long thread passes `References: fitReferences(references)`, which fits both. Neither takes `Message-ID`, `Date` or the address headers as custom headers.
+- **A To.** The Email SDK asks for one: a message to Cc or Bcc alone goes To its sender, as many mail clients do.
+- **Size.** Email Service takes up to 5 MiB, attachments included (25 MiB to the account's verified destination addresses), and 32 attachments; SES 40 MB, the base64 encoding counted. Both take 50 recipients.
+- **Tags.** SES message tags (`mail.tags`) come back on every SES event about the message; the binding has none and drops them.
+- **List mail.** Email Service takes transactional mail only, so newsletters and other list mail go through `sendWithSes`, which never falls back.
+- **Idempotency.** Neither has any; a caller that retries can deliver twice.
+
+## Exports
+
+From `@rivi-software/workers-mail`:
+
+| Export | What |
+| --- | --- |
+| `sendMail(env, mail)` | Transactional mail: SES when `env` holds its region and key, else `env.EMAIL`, and `env.EMAIL` when SES refuses the message ([How it works](#how-it-works)). Answers `SentMail`: the `transport`, the provider's `id` and the `messageId` header. |
+| `sendWithSes(config, mail, { configurationSet })` | SES alone, never the binding: list mail, which Email Service does not take, with the configuration set whose event destinations report its bounces and complaints. |
+| `sendWithBinding(binding, mail)` | The binding alone. |
+| `canSendMail(env)`, `sesConfig(env)` | Whether a Worker can send at all; SES's region and key, or null while one of them is missing. |
+| `MailError` | A message that was not sent: `transport`, SES's HTTP `status` (absent when SES was not reached or the binding failed), `code` (SES's error type such as `MessageRejected`, or the binding's such as `E_RATE_LIMIT_EXCEEDED`) and `refusedMessage`, true when SES refused the message itself, so that sending it again fails the same way. |
+| `sesError(response)` | The `MailError` for an error answer from SES's API, for calls the Email SDK does not make, such as reading the account's quota with `GetAccount`. |
+| `addressParts(address)` | `{ email, name }` for any `MailAddress`. |
+| `formatSesAddress(address)` | The address as SES takes it: the name quoted, or MIME-encoded when it is not ASCII. |
+| `fitReferences(value, max = 986)` | A `References` value cut to `max` characters: the first message and the latest. |
+| `sesMessageId(region, id)` | The `Message-ID` header SES gives the message it answered `id` for. |
+| Types | `Mail`, `MailAddress`, `MailAttachment`, `MailEnv`, `MailTransport`, `SentMail`, `SesConfig`, `EmailBinding`. |
+
+A `Mail` has `from`, `to` (one address or a list), `cc`, `bcc` and `replyTo`, each address as `jane@example.com`, `Jane <jane@example.com>` or `{ email, name }`; a `subject`; `text` and/or `html`; `headers`; `attachments` as base64 (`disposition` `attachment`, or `inline` with the `contentId` the HTML names as `cid:`); and SES message `tags`.
+
+From `@rivi-software/workers-mail/address`:
+
+| Export | What |
+| --- | --- |
+| `parseMailAddress(raw)` | `{ email, name }` for `jane@example.com`, `Jane <jane@example.com>` or `"Jane Doe" <jane@example.com>`, and anything else as an address alone. It reads each character a fixed number of times, so a long or crafted name costs its length and no more. The entry point is its own so a browser bundle, an address field in a form, leaves the Email SDK out. |
+
+## Telemetry
+
+The Email SDK reports every client it creates and every send to its maker's PostHog unless told not to. When the package loads, it calls the SDK's `disableTelemetry()`, which turns that off for the whole process, Email SDK clients that your own code creates included, and every client the package creates passes `telemetry: false` as well. [`tests/mail.test.ts`](https://github.com/rivi-software/tools/blob/main/packages/workers-mail/tests/mail.test.ts) checks that a send makes one request, to SES, with `NODE_ENV` and the SDK's opt-out variables out of the way.
+
+## Setting up SES
+
+Until these steps are done the binding sends everything, so they can wait until SES is needed. In the AWS console, in the region the Worker will send from, and in the DNS of each domain it sends from:
+
+1. **Identity.** SES → Identities → Create identity → Domain: `<domain>`, with Easy DKIM (RSA 2048-bit), and its three DKIM CNAME records in the domain's DNS (DNS only, if Cloudflare serves it). They use selectors of their own, so they sit beside Email Service's DKIM record and both keep signing. A custom MAIL FROM domain, such as `ses-bounce.<domain>` (Email Service uses `cf-bounce.<domain>`), with the MX and TXT records SES lists, aligns SPF as well; DKIM alone already passes DMARC.
+2. **Production access.** A new SES account is in the sandbox: it sends only to verified addresses, 200 messages a day. Ask for production access on SES's account dashboard; until SES grants it, it refuses other recipients with `MessageRejected` and the binding sends their mail.
+3. **Key.** An IAM user for each Worker with only `ses:SendEmail` on the identity, for the addresses the Worker sends from, and an access key for it, which goes into the Worker's two secrets; `SES_REGION` is a var in its config ([Usage](#usage)).
+
+   ```json
+   {
+     "Version": "2012-10-17",
+     "Statement": [
+       {
+         "Effect": "Allow",
+         "Action": "ses:SendEmail",
+         "Resource": "arn:aws:ses:<region>:<account id>:identity/<domain>",
+         "Condition": { "StringLike": { "ses:FromAddress": ["<address>"] } }
+       }
+     ]
+   }
+   ```
+
+   `ses:FromAddress` takes wildcards (`*@<domain>`). A Worker that sends with a configuration set (`sendWithSes`) also needs `ses:SendEmail` on that set: add `arn:aws:ses:<region>:<account id>:configuration-set/<name>` to `Resource`.
+4. **Check.** Send what the Worker sends (a sign-in link, a password reset) and look in its logs (Workers Logs, `wrangler tail`): no `mail.ses_refused` line means SES took the message. A line names SES's error type: `UnrecognizedClientException` or `SignatureDoesNotMatch` is the key, `AccessDeniedException` the IAM policy, `MessageRejected` with "not verified" the identity or the sandbox. Until it is fixed the binding keeps sending. Deleting the two secrets goes back to the binding.
+
+SES's account-level suppression list (SES → Configuration → Suppression list) keeps it from sending again to an address that bounced or complained; check that it covers both. `sendMail` uses no configuration set, so its mail has no event destination.
+
+## Testing a Worker that sends
+
+The package's own tests run in Node with Vitest: SES is answered by a spy on the global `fetch`, which the package looks up on each call, and the binding by an object that records what it was handed. A Worker's tests can do the same: leave the three SES values empty and pass an `EMAIL` that records the mail, or set them and spy on `fetch` to answer as SES does ([`tests/mail.test.ts`](https://github.com/rivi-software/tools/blob/main/packages/workers-mail/tests/mail.test.ts) has both).
+
+## Limits
+
+- Workers need Node.js compatibility for the Email SDK's Node imports: the default from compatibility date 2026-08-04, the `nodejs_compat` flag before it.
+- No retries, and no idempotency in either transport: a caller that retries can deliver twice.
+- `References` is fitted for SES alone; Email Service refuses a header value over 2,048 bytes ([Headers](#how-it-works)).
+- Attachments are base64 strings: Email Service's local simulator in `wrangler dev` cannot take an `ArrayBuffer`, and SES wants base64.
+- Through the binding, recipients' display names are dropped.
+
+## Development
+
+The tests in `tests/` cover both transports and the fallback between them against a stand-in SES and binding, the addresses and headers each transport takes, the telemetry opt-out (`mail.test.ts`) and the address parser (`address.test.ts`). None of them sends mail. In this directory, run `pnpm run test`, `pnpm run check` and `pnpm run build`.
+
+## License
+
+[MIT](LICENSE)

package/dist/address.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `jane@example.com`, `Jane <jane@example.com>` or `"Jane Doe" <jane@example.com>` as the address and its
+ * display name, the address as written; anything else is an address alone. Each character is read a fixed number
+ * of times: a regex that lets the name and the space before `<` take the same whitespace backtracks, so a name of
+ * 20,000 spaces takes a second. An entry point of its own, `@rivi-software/workers-mail/address`, so a browser
+ * bundle leaves the Email SDK out.
+ */
+export declare function parseMailAddress(raw: string): {
+    email: string;
+    name: string | null;
+};

package/dist/address.js

@@ -0,0 +1,24 @@
+/**
+ * `jane@example.com`, `Jane <jane@example.com>` or `"Jane Doe" <jane@example.com>` as the address and its
+ * display name, the address as written; anything else is an address alone. Each character is read a fixed number
+ * of times: a regex that lets the name and the space before `<` take the same whitespace backtracks, so a name of
+ * 20,000 spaces takes a second. An entry point of its own, `@rivi-software/workers-mail/address`, so a browser
+ * bundle leaves the Email SDK out.
+ */
+export function parseMailAddress(raw) {
+    const address = raw.trim();
+    // The address is the last `<…>`: a quoted display name may hold a `<` of its own.
+    const open = address.lastIndexOf("<");
+    if (open >= 0 && address.endsWith(">")) {
+        const email = address.slice(open + 1, -1);
+        let name = address.slice(0, open).trim();
+        if (name.startsWith('"'))
+            name = name.slice(1);
+        if (name.endsWith('"'))
+            name = name.slice(0, -1);
+        // A quote inside the name, or a `>` inside the brackets, is not a form this reads.
+        if (email && !email.includes(">") && !name.includes('"'))
+            return { email: email.trim(), name: name.trim() || null };
+    }
+    return { email: address, name: null };
+}

package/dist/index.d.ts

@@ -0,0 +1,125 @@
+/** `jane@example.com`, `Jane <jane@example.com>`, or the address with its display name apart. */
+export type MailAddress = string | {
+    email: string;
+    name?: string | null;
+};
+/** A file sent with the message: an attachment, or an inline image the HTML names as `cid:<contentId>`. */
+export type MailAttachment = {
+    filename: string;
+    /** The MIME type. */
+    type: string;
+    /** The bytes, base64-encoded: local dev's binding cannot take an ArrayBuffer, and SES wants base64. */
+    content: string;
+} & ({
+    disposition: "attachment";
+    contentId?: undefined;
+} | {
+    disposition: "inline";
+    contentId: string;
+});
+/** A message for `sendMail`, `sendWithSes` or `sendWithBinding`; `text`, `html` or both. */
+export type Mail = {
+    from: MailAddress;
+    to: MailAddress | readonly MailAddress[];
+    cc?: readonly MailAddress[];
+    bcc?: readonly MailAddress[];
+    replyTo?: MailAddress;
+    subject: string;
+    text?: string;
+    html?: string;
+    /** Headers SES and Email Service let a sender set: `In-Reply-To`, `References`, `List-Unsubscribe`, `Auto-Submitted`… */
+    headers?: Record<string, string>;
+    attachments?: readonly MailAttachment[];
+    /** SES message tags, handed back on every event about the message; the binding has none and drops them. */
+    tags?: Record<string, string>;
+};
+/** Which transport sent a message: Amazon SES, or Cloudflare Email Service's binding. */
+export type MailTransport = "ses" | "email-service";
+/** What `sendMail` answers once a message went out. */
+export type SentMail = {
+    transport: MailTransport;
+    /** The provider's id for the message: SES's `MessageId`, or the binding's `messageId`. */
+    id: string | null;
+    /** The `Message-ID` header the message went out with, `<…>`, which a reply names in `In-Reply-To`. */
+    messageId: string | null;
+};
+/** Cloudflare Email Service's `send_email` binding, typed loosely so `SendEmail` and a test's stand-in both fit. */
+export type EmailBinding = {
+    send(message: never): Promise<unknown>;
+};
+/** What a Worker sends with: SES's region and an IAM user's key, the `EMAIL` binding, or both. */
+export type MailEnv = {
+    EMAIL?: EmailBinding;
+    SES_REGION?: string;
+    SES_ACCESS_KEY_ID?: string;
+    SES_SECRET_ACCESS_KEY?: string;
+};
+/** SES's region and an IAM user's access key, as `sesConfig` reads them from the Worker's env. */
+export type SesConfig = {
+    region: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+};
+/** A message that was not sent: what the transport answered, with SES's error type or the binding's code. */
+export declare class MailError extends Error {
+    readonly transport: MailTransport;
+    /** The HTTP status SES answered with; absent when SES was not reached or the binding failed. */
+    readonly status: number | undefined;
+    /** SES's error type (`MessageRejected`, `TooManyRequestsException`) or the binding's (`E_RATE_LIMIT_EXCEEDED`). */
+    readonly code: string | undefined;
+    constructor(message: string, options: {
+        transport: MailTransport;
+        status?: number;
+        code?: string;
+        cause?: unknown;
+    });
+    /**
+     * Whether SES refused this message itself (an address it will not take, a recipient the sandbox has not
+     * verified), so sending it again fails the same way. Anything else is about the account, its quota, its setup
+     * or the network, and passes.
+     */
+    get refusedMessage(): boolean;
+}
+/** SES's region and key from the Worker's vars and secrets, or null while any of the three is missing. */
+export declare function sesConfig(env: MailEnv): SesConfig | null;
+/** Whether the Worker can send at all: through SES or the binding. */
+export declare function canSendMail(env: MailEnv): boolean;
+/**
+ * Sends a transactional message: through Amazon SES when the Worker holds its key, else through the `EMAIL`
+ * binding. When SES answers with a refusal (its identity not verified yet, the IAM user not allowed to send as
+ * the address, a throttle) nothing went out, so the binding sends it instead and a `mail.ses_refused` line says
+ * why. Without an answer from SES (the network, a timeout) the message may have gone out, and the error stands:
+ * sending it again could deliver it twice. List mail never comes here (`sendWithSes`): Email Service takes
+ * transactional mail only.
+ */
+export declare function sendMail(env: MailEnv, mail: Mail): Promise<SentMail>;
+/** Sends through Amazon SES (API v2) alone; `configurationSet` names the set whose event destinations see it. */
+export declare function sendWithSes(config: SesConfig, mail: Mail, options?: {
+    configurationSet?: string;
+}): Promise<SentMail>;
+/** Sends through Email Service's `send_email` binding alone. Recipients go as bare addresses, as it requires. */
+export declare function sendWithBinding(binding: EmailBinding, mail: Mail): Promise<SentMail>;
+/** An address with its display name apart; `Jane <jane@example.com>` and `"Jane" <jane@example.com>` are read too. */
+export declare function addressParts(address: MailAddress): {
+    email: string;
+    name: string | null;
+};
+/**
+ * An address as SES's `FromEmailAddress`, `ToAddresses` and `ReplyToAddresses` take it: the name quoted, or
+ * MIME-encoded (RFC 2047) when it is not plain ASCII, since SES refuses raw UTF-8 there.
+ */
+export declare function formatSesAddress(address: MailAddress): string;
+/**
+ * `References` cut to `max` characters the way RFC 5537 (3.4.4) trims it: the thread's first message, then as many
+ * of the latest as fit, in order. Clients thread on the first and the last, which both stay. `max` defaults to what
+ * SES takes, 986.
+ */
+export declare function fitReferences(value: string, max?: number): string;
+/**
+ * The `Message-ID` SES gives a message it sent: its `MessageId` at the region's sending domain (`email` stands for
+ * us-east-1). SES writes the Message-ID itself and takes none from a sender, so this is how a reply finds its way
+ * back to the thread.
+ */
+export declare function sesMessageId(region: string, id: string): string;
+/** The `MailError` for an error answer from SES: the type from `x-amzn-ErrorType` or the body's `__type`. */
+export declare function sesError(res: Response): Promise<MailError>;

package/dist/index.js

@@ -0,0 +1,238 @@
+import { createEmailClient, disableTelemetry, } from "@opencoredev/email-sdk";
+import { cloudflare } from "@opencoredev/email-sdk/cloudflare";
+import { ses } from "@opencoredev/email-sdk/ses";
+import { parseMailAddress } from "./address.js";
+// The SDK reports every client and send to its maker's PostHog unless told not to. Off for the whole process,
+// clients that other code creates included; every client here is created with `telemetry: false` as well.
+disableTelemetry();
+/** A message that was not sent: what the transport answered, with SES's error type or the binding's code. */
+export class MailError extends Error {
+    transport;
+    /** The HTTP status SES answered with; absent when SES was not reached or the binding failed. */
+    status;
+    /** SES's error type (`MessageRejected`, `TooManyRequestsException`) or the binding's (`E_RATE_LIMIT_EXCEEDED`). */
+    code;
+    constructor(message, options) {
+        super(message, { cause: options.cause });
+        this.name = "MailError";
+        this.transport = options.transport;
+        this.status = options.status;
+        this.code = options.code;
+    }
+    /**
+     * Whether SES refused this message itself (an address it will not take, a recipient the sandbox has not
+     * verified), so sending it again fails the same way. Anything else is about the account, its quota, its setup
+     * or the network, and passes.
+     */
+    get refusedMessage() {
+        return this.code === "MessageRejected" || this.code === "BadRequestException";
+    }
+}
+/** SES's region and key from the Worker's vars and secrets, or null while any of the three is missing. */
+export function sesConfig(env) {
+    const region = env.SES_REGION?.trim();
+    const accessKeyId = env.SES_ACCESS_KEY_ID?.trim();
+    const secretAccessKey = env.SES_SECRET_ACCESS_KEY?.trim();
+    return region && accessKeyId && secretAccessKey ? { region, accessKeyId, secretAccessKey } : null;
+}
+/** Whether the Worker can send at all: through SES or the binding. */
+export function canSendMail(env) {
+    return Boolean(sesConfig(env) || env.EMAIL);
+}
+/**
+ * Sends a transactional message: through Amazon SES when the Worker holds its key, else through the `EMAIL`
+ * binding. When SES answers with a refusal (its identity not verified yet, the IAM user not allowed to send as
+ * the address, a throttle) nothing went out, so the binding sends it instead and a `mail.ses_refused` line says
+ * why. Without an answer from SES (the network, a timeout) the message may have gone out, and the error stands:
+ * sending it again could deliver it twice. List mail never comes here (`sendWithSes`): Email Service takes
+ * transactional mail only.
+ */
+export async function sendMail(env, mail) {
+    const config = sesConfig(env);
+    if (config) {
+        try {
+            return await sendWithSes(config, mail);
+        }
+        catch (err) {
+            if (!(err instanceof MailError && err.status !== undefined && env.EMAIL))
+                throw err;
+            // The code and status only: SES's message can name the recipient.
+            console.warn(JSON.stringify({ event: "mail.ses_refused", status: err.status, code: err.code }));
+        }
+    }
+    if (!env.EMAIL)
+        throw new MailError("No mail transport: neither Amazon SES nor the EMAIL binding is set up.", {
+            transport: "email-service",
+        });
+    return sendWithBinding(env.EMAIL, mail);
+}
+/** Sends through Amazon SES (API v2) alone; `configurationSet` names the set whose event destinations see it. */
+export async function sendWithSes(config, mail, options = {}) {
+    const adapter = ses({
+        ...config,
+        configurationSetName: options.configurationSet?.trim() || undefined,
+        fetch: sesFetch,
+    });
+    const result = await send(adapter, "ses", {
+        ...envelope(mail, formatSesAddress, formatSesAddress),
+        headers: mail.headers && sesHeaders(mail.headers),
+        tags: mail.tags && Object.entries(mail.tags).map(([name, value]) => ({ name, value })),
+    });
+    return {
+        transport: "ses",
+        id: result.id,
+        messageId: result.id ? sesMessageId(config.region, result.id) : null,
+    };
+}
+/** Sends through Email Service's `send_email` binding alone. Recipients go as bare addresses, as it requires. */
+export async function sendWithBinding(binding, mail) {
+    const adapter = cloudflare({ binding: binding });
+    const result = await send(adapter, "email-service", {
+        ...envelope(mail, (a) => addressParts(a).email, bindingAddress),
+        headers: mail.headers && Object.entries(mail.headers).map(([name, value]) => ({ name, value })),
+    });
+    return { transport: "email-service", id: result.id, messageId: result.id };
+}
+async function send(adapter, transport, message) {
+    try {
+        const client = createEmailClient({ adapters: [adapter], telemetry: false });
+        const result = await client.send(message);
+        return { id: result.id ?? null };
+    }
+    catch (err) {
+        throw mailError(err, transport);
+    }
+}
+/** The Email SDK's message from ours: recipients and senders formatted for the transport, the parts as they are. */
+function envelope(mail, recipient, sender) {
+    const list = (addresses) => addresses === undefined
+        ? undefined
+        : (Array.isArray(addresses) ? addresses : [addresses]).map(recipient);
+    const to = list(mail.to) ?? [];
+    const cc = list(mail.cc);
+    const bcc = list(mail.bcc);
+    return {
+        from: sender(mail.from),
+        // The Email SDK asks for a To: a message to Cc or Bcc alone goes To its sender, as many mail clients do.
+        to: to.length || !(cc?.length || bcc?.length) ? to : [recipient(mail.from)],
+        ...(cc?.length ? { cc } : {}),
+        ...(bcc?.length ? { bcc } : {}),
+        ...(mail.replyTo ? { replyTo: sender(mail.replyTo) } : {}),
+        subject: mail.subject,
+        ...(mail.text !== undefined ? { text: mail.text } : {}),
+        ...(mail.html !== undefined ? { html: mail.html } : {}),
+        ...(mail.attachments?.length
+            ? {
+                attachments: mail.attachments.map((a) => ({
+                    filename: a.filename,
+                    contentType: a.type,
+                    content: a.content,
+                    contentEncoding: "base64",
+                    disposition: a.disposition,
+                    ...(a.contentId ? { contentId: a.contentId } : {}),
+                })),
+            }
+            : {}),
+    };
+}
+/** An address with its display name apart; `Jane <jane@example.com>` and `"Jane" <jane@example.com>` are read too. */
+export function addressParts(address) {
+    if (typeof address !== "string")
+        return { email: address.email, name: address.name?.trim() || null };
+    return parseMailAddress(address);
+}
+function bindingAddress(address) {
+    const { email, name } = addressParts(address);
+    return name ? { email, name } : email;
+}
+/**
+ * An address as SES's `FromEmailAddress`, `ToAddresses` and `ReplyToAddresses` take it: the name quoted, or
+ * MIME-encoded (RFC 2047) when it is not plain ASCII, since SES refuses raw UTF-8 there.
+ */
+export function formatSesAddress(address) {
+    const { email, name } = addressParts(address);
+    if (!name)
+        return email;
+    if (/^[ -~]*$/.test(name))
+        return `"${name.replace(/["\\]/g, "\\$&")}" <${email}>`;
+    const bytes = new TextEncoder().encode(name);
+    return `=?UTF-8?B?${btoa(String.fromCharCode(...bytes))}?= <${email}>`;
+}
+/**
+ * SES takes a header of at most 996 characters, its name and value together (a line of 998 with the `: `), so a
+ * long thread's `References` is shortened to the 986 that leaves it.
+ */
+const SES_HEADER_MAX = 996;
+function sesHeaders(headers) {
+    return Object.entries(headers).map(([name, value]) => ({
+        name,
+        value: name.toLowerCase() === "references"
+            ? fitReferences(value, SES_HEADER_MAX - name.length)
+            : value,
+    }));
+}
+/**
+ * `References` cut to `max` characters the way RFC 5537 (3.4.4) trims it: the thread's first message, then as many
+ * of the latest as fit, in order. Clients thread on the first and the last, which both stay. `max` defaults to what
+ * SES takes, 986.
+ */
+export function fitReferences(value, max = SES_HEADER_MAX - "References".length) {
+    if (value.length <= max)
+        return value;
+    const ids = value.split(/\s+/).filter(Boolean);
+    const first = ids[0];
+    const latest = [];
+    let length = first.length;
+    for (let i = ids.length - 1; i > 0; i--) {
+        if (length + 1 + ids[i].length > max)
+            break;
+        latest.unshift(ids[i]);
+        length += 1 + ids[i].length;
+    }
+    return [first, ...latest].join(" ");
+}
+/**
+ * The `Message-ID` SES gives a message it sent: its `MessageId` at the region's sending domain (`email` stands for
+ * us-east-1). SES writes the Message-ID itself and takes none from a sender, so this is how a reply finds its way
+ * back to the thread.
+ */
+export function sesMessageId(region, id) {
+    return `<${id}@${region === "us-east-1" ? "email" : region}.amazonses.com>`;
+}
+/**
+ * `fetch` for the SES adapter: an error answer becomes a `MailError` with SES's error type, which the Email SDK
+ * would otherwise fold into its message. The global `fetch` is looked up on each call, so a test's spy reaches it.
+ */
+async function sesFetch(input, init) {
+    const res = await fetch(input, init);
+    if (res.ok)
+        return res;
+    throw await sesError(res);
+}
+/** The `MailError` for an error answer from SES: the type from `x-amzn-ErrorType` or the body's `__type`. */
+export async function sesError(res) {
+    const body = (await res.json().catch(() => ({})));
+    // "TooManyRequestsException:http://internal.amazon.com/coral/…" or "com.amazonaws…#MessageRejected".
+    const type = res.headers.get("x-amzn-errortype") ?? String(body.__type ?? `HTTP${res.status}`);
+    const code = type.split(":")[0].split("#").pop();
+    return new MailError(String(body.message ?? body.Message ?? res.statusText), {
+        transport: "ses",
+        status: res.status,
+        code,
+    });
+}
+/** What the Email SDK threw, as a `MailError`: SES's own when it answered, else the innermost error's words and code. */
+function mailError(err, transport) {
+    let root = err;
+    for (let e = err; e instanceof Error; e = e.cause) {
+        if (e instanceof MailError)
+            return e;
+        root = e;
+    }
+    const code = root?.code;
+    return new MailError(root instanceof Error ? root.message : String(root), {
+        transport,
+        code: typeof code === "string" ? code : undefined,
+        cause: err,
+    });
+}

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@rivi-software/workers-mail",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "Mail from Cloudflare Workers: Amazon SES once the Worker holds its key, Cloudflare Email Service's send_email binding until then and whenever SES refuses a message",
+  "keywords": [
+    "cloudflare",
+    "cloudflare-workers",
+    "email",
+    "transactional-email",
+    "amazon-ses",
+    "ses",
+    "cloudflare-email-service",
+    "send-email"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./address": {
+      "types": "./dist/address.d.ts",
+      "default": "./dist/address.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "@opencoredev/email-sdk": "^3.0.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rivi-software/tools.git",
+    "directory": "packages/workers-mail"
+  },
+  "homepage": "https://github.com/rivi-software/tools/tree/main/packages/workers-mail#readme",
+  "bugs": "https://github.com/rivi-software/tools/issues",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "check": "tsc --noEmit",
+    "test": "vitest run"
+  }
 }