Email Transport Failclosed

The bug this exists to prevent

Every project grows a ConsoleTransport for local development: log the email, return success, move on. It is the obvious stub and it is the wrong shape.

The moment that stub reaches an environment with no provider key configured — a preview deploy, a new staging box, a production box after a key rotation — **every receipt, password reset and invite reports success and vanishes.** Nothing errors. The order says the receipt was sent. The customer says they never got it, and there is no evidence either way.

ok: false is the honest answer for a transport that logged to a console. It costs nothing in development, where nobody checks the return value, and it is the difference between a silent outage and a visible one everywhere else.

Rule 2 — never throw into a request path

A provider error response and a failed network call both return ok: false. Neither throws.

An email that fails must not take down the checkout that triggered it. The purchase is the important thing; the receipt is recoverable and can be retried from the order. Throwing inverts that — a transient email outage becomes failed payments.

Rule 3 — the interface, not the SDK

The transport is an interface with adapters, so a provider swap is a new adapter rather than a rewrite, and tests run with no key and no network.

This also means the package has no provider dependency: the Resend adapter is a fetch call with a bearer token, roughly twenty lines. Pulling in an SDK to make one HTTP request is how a transactional email layer acquires a dependency tree.

What this does NOT do

No templating, no queueing, no retry, no scheduling, no bounce or complaint handling, no suppression list. It sends one message and tells you honestly whether it went.

Retries belong to whatever owns the order, because that is the thing that knows if the receipt still matters.

Verified

7 tests: the console transport reporting ok: false and never throwing, the Resend adapter posting with a bearer token and returning a message id, ok: false on a provider error response, ok: false on a network failure, and transport resolution.

Not covered: no test hits the real Resend API — the adapter is asserted against a stubbed fetch, so a change in their response shape would not be caught here.