Molecule.dev

@molecule/api-emails-capture

Provider bond · email · API (Node) · v1.0.3 · Apache-2.0

Email capture provider for molecule.dev

npm install @molecule/api-emails-capture

npm · Source on GitHub · Implements @molecule/api-emails

How it works

@molecule/api-emails-capture is a provider bond on the API (Node) side: it implements the email core interface (@molecule/api-emails) with a concrete vendor or library behind it.

Your code calls the core; you wire this provider once at startup. Swapping vendors later is one line in that wiring, not a rewrite.

import { setTransport } from '@molecule/api-emails'
import { createEmailCaptureProvider, provider } from '@molecule/api-emails-capture'

setTransport(provider) // intercept-only: nothing is actually delivered

// Tee mode: really send AND record the real outcome
// import { createTransport } from '@molecule/api-emails-mailgun'
// setTransport(createEmailCaptureProvider(createTransport()))

Works with: @molecule/api-activity, @molecule/api-emails

Reference

Email capture provider for molecule.dev.

Records every sendMail() call as an activity event. Intercept-only by default (synthetic success); delegates + tees when wrapping a real transport.

Auto-generated, AI-first package reference for the molecule.dev ecosystem. It is written to be read by coding agents as much as by people, and is generated from this package's source — edit src/index.ts JSDoc, not this file.

Quick Start

import { setTransport } from '@molecule/api-emails'
import { createEmailCaptureProvider, provider } from '@molecule/api-emails-capture'

setTransport(provider) // intercept-only: nothing is actually delivered

// Tee mode: really send AND record the real outcome
// import { createTransport } from '@molecule/api-emails-mailgun'
// setTransport(createEmailCaptureProvider(createTransport()))

Type

provider

Installation

npm install @molecule/api-emails-capture @molecule/api-activity @molecule/api-emails

API

Functions

createEmailCaptureProvider(realTransport)

Creates an email capture transport.

When realTransport is provided, each message is delivered through it and the captured event records the real outcome (delegate + tee). When omitted (the dev default), messages are intercepted and a synthetic success result is returned.

function createEmailCaptureProvider(realTransport?: EmailTransport): EmailTransport
  • realTransport — Optional real transport to delegate to and tee.

Returns: An EmailTransport that records activity for every send.

Constants

provider

Default email capture transport (intercept-only).

const provider: EmailTransport

Core Interface

Implements @molecule/api-emails interface.

Bond Wiring

Setup function to register this provider with the core interface:

import { setTransport } from '@molecule/api-emails'
import { provider } from '@molecule/api-emails-capture'

export function setupEmailsCapture(): void {
  setTransport(provider)
}

Injection Notes

Requirements

Peer dependencies:

  • @molecule/api-activity ^1.0.1
  • @molecule/api-emails ^1.0.1

Runtime Dependencies

  • @molecule/api-activity

  • @molecule/api-emails

  • Two modes, and the choice decides whether mail is DELIVERED. INTERCEPT-ONLY (provider, or createEmailCaptureProvider() with no argument) records the message and returns a synthetic success — nothing reaches the recipient; that is the dev experience ("captured, not delivered"). DELEGATE + TEE (createEmailCaptureProvider(realTransport)) sends through the real transport AND records the real outcome. Anywhere real mail must go out (production), wrap the real transport — never bond the intercept-only provider.

  • Recording is best-effort: a bonded ActivitySink that throws NEVER changes the outcome of sendMail() — a successful real send always resolves successfully and a failed real send always rejects with the REAL transport error, even if the activity record itself failed. This matters because a naive delegate-then-record implementation can turn an actually-SENT email into an apparent failure, causing callers to retry and recipients to get duplicates.

  • Captured events go to the bonded activity sink (@molecule/api-activity). Without a sink bonded, record() is a silent no-op.

E2E Tests

Integration checklist — drive the real UI (live preview, no mocks). The sandbox CAPTURES outbound email instead of sending — read each message with the read_activity tool (filter type 'email'); the verification/reset link is in its payload. Never mock the send or modify production code to expose it. Adapt each item to this app's actual screens/flows, and check every box off one by one. A box you can't check is an integration bug to fix — not a skip:

  • Each email-triggering flow (signup verification, password-reset request, invites/notifications the app defines) confirms the send in the UI ("check your inbox") and a message actually reaches the transport.
  • The password-reset round-trip completes: request a reset → open the captured message → follow its single-use link → set a new password → log in with it (and the old password no longer works).
  • The message body contains a LINK, never the raw token/secret, and renders with the app's real name/content (no undefined placeholders).
  • Requesting a reset for an unknown email shows the same neutral UI response as a known one (no account-existence oracle).
  • Account emails go only to the account's own address — no UI or endpoint lets an unauthenticated caller send to an arbitrary address.