@stackbilt/email

Cloudflare-native transactional email package with a provider-agnostic transport interface.

Install

pnpm add @stackbilt/email

Why this package

• Built for Cloudflare Workers send_email
• Clean transport abstraction for future providers
• Safe local console transport for development/CI
• App helper methods via EmailClient

Usage

import { createCloudflareEmailClient } from "@stackbilt/email";

const email = createCloudflareEmailClient(env.EMAIL, {
  appName: "StackBilt",
  defaultFrom: "[email protected]",
  defaultReplyTo: "[email protected]",
});

await email.send({
  to: "[email protected]",
  subject: "Test email",
  text: "It works.",
  html: "<p>It works.</p>",
});

Helper methods

await email.sendMagicLink({ to, url });
await email.sendContactForm({
  to: "[email protected]",
  fromName: "Jane Doe",
  fromEmail: "[email protected]",
  message: "Need help with billing",
});

API

createCloudflareEmailClient(binding, config)

Creates an EmailClient backed by CloudflareEmailTransport.

Config:

• appName: string
• defaultFrom: EmailAddress
• defaultReplyTo?: EmailAddress

EmailTransport

Provider-agnostic interface:

interface EmailTransport {
  send(input: SendEmailInput): Promise<{ messageId: string }>;
}

CloudflareEmailTransport

• Requires either text or html.
• Uses configured default sender when from is omitted.
• Returns normalized { messageId }.

ConsoleEmailTransport

• Logs metadata only (to, from, subject, content flags).
• Does not log full email body by default.

Cloudflare Binding

[[send_email]]
name = "EMAIL"
allowed_sender_addresses = [
  "[email protected]",
  "[email protected]"
]

Local Development

pnpm build
pnpm typecheck

Security Notes

• Keep credentials in Worker bindings/secrets.
• Do not commit .env.
• Guard debug/test routes in non-production environments.