Email SDK
Provider-portable transactional email for Bijection with durable queues, retries, fallback adapters, idempotency, webhooks, and reactive status.
git clone https://github.com/bijectionhq/email-sdk.git
cd email-sdk
git checkout fe6ec67063930027228f021d6e67ca5cd5d6dbd1
cd packages/convex-emailBijection repository access is required. Request access.
Description
Provider-portable transactional email for Bijection with durable queues, retries, fallback adapters, idempotency, webhooks, and reactive status.
Explore the package README for API concepts, configuration, and examples. Check the Bijection source for adaptation-specific setup.
Review the source and its dependencies before adopting this package. Source availability does not establish npm publication or runtime qualification.
Getting started
- Get the source at the revision above and read its package documentation.
- Check the required Bijection SDK version, dependencies, and external service credentials.
- Follow the package setup instructions and the guide to using components.
- Exercise the component in your deployment according to your project’s verification rules.
Open source
Maintained source: bijectionhq/email-sdk. Based on opencoredev/email-sdk. License: MIT. Consult the repository for license terms, notices, and contributor attribution.
From the upstream publisher
Provider-portable transactional email for Convex with durable queues, retries, fallback adapters, idempotency, webhooks, and reactive status.
Explore the demo ↗Upstream overview
From the upstream package documentation.
Email SDK provides a single TypeScript client for sending transactional email across 23 provider adapters including Resend, Postmark, SendGrid, AWS SES, and SMTP. It normalizes the message format across providers, adds retry logic and fallback routing between adapters, and surfaces unsupported field errors before data is silently dropped. Convex actions can use it server-side to trigger emails from mutations, scheduled functions, or webhooks.
Use cases
From the upstream package documentation.
- Sending welcome or transactional emails from a Convex action without coupling your code to a single provider's API
- Switching email providers without rewriting send logic, using the same normalized message interface across all 23 adapters
- Configuring fallback routes so that if your primary provider fails, sends automatically retry through a secondary adapter
- Validating that a message's fields are supported by the target provider before the send, avoiding silent data loss
- Running dry-run smoke tests against real provider configs in CI using the built-in test adapters and CLI doctor command
How it works
From the upstream package documentation.
Initialize a client with createEmailClient from @opencoredev/email-sdk, passing an array of adapter instances. Each adapter is imported from its own entry point, for example import { resend } from '@opencoredev/email-sdk/resend', and configured with provider credentials. The client exposes a single email.send() method that accepts a normalized message object with from, to, subject, and html fields.
Retries and fallback routing are configured at the client level. If the first adapter in the array fails, the SDK can route the send through subsequent adapters. Field-support checks run before the send, so unsupported fields raise an error rather than being silently ignored by the provider.
Because the SDK is server-side only and requires Node 20+ or Bun, it should be called from Convex actions rather than queries or mutations directly. API keys are passed via environment variables and never exposed to client code. Observability hooks for logs, metrics, and traces can be attached at client creation time. Telemetry is disabled automatically when NODE_ENV=test or can be opted out via the EMAIL_SDK_TELEMETRY=0 environment variable.
Upstream package FAQ
What Convex function type should I use to send email with this SDK?
Email sends must run inside a Convex action, not a mutation or query. Convex actions are designed for calling third-party services and external APIs. Import createEmailClient from @opencoredev/convex-email inside your action file and keep provider API keys in environment variables, never in client-side code.
Which email providers does @opencoredev/convex-email support?
The SDK includes 23 adapters: Resend, Postmark, SendGrid, AWS SES, Mailgun, Brevo, MailerSend, SparkPost, Mailchimp, Iterable, Loops, Plunk, Mailtrap, Cloudflare, Unosend, Scaleway, ZeptoMail, MailPace, Sequenzy, JetEmail, Lettermint, Primitive, SMTP, and a test adapter. Each adapter is imported from its own entry point, for example @opencoredev/email-sdk/resend.
Does the SDK work in Convex's serverless environment?
Email SDK is server-side only and requires Node 20 or Bun. Convex actions run in a Node.js-compatible environment, so the SDK is compatible when used inside actions. Do not import it into client-side Convex code or browser bundles.
How do I test email sends without calling a real provider?
Email SDK ships a dedicated test adapter that never calls real provider APIs. Import it in place of your production adapter during tests. Combined with the fact that telemetry is automatically disabled when NODE_ENV=test, this makes it straightforward to write unit tests for actions that send email.
Does @opencoredev/convex-email collect any data about my emails?
Email SDK collects anonymous usage analytics tied to a random local ID, covering adapter names, success or failure, send duration, and SDK version. Email content, subjects, recipient addresses, API keys, and attachments are never collected. You can opt out by setting EMAIL_SDK_TELEMETRY=0 or passing telemetry: false to createEmailClient.
Use with agents and CLI
Give your coding agent the component’s source identity and setup guidance.
Help me integrate Email SDK with Bijection.
Read: https://bijection.com/components/email-sdk/SKILL.md
Check SDK compatibility and dependency availability.
Follow this project's execution and verification rules.Upstream README.md
View repository ↗Documentation from opencoredev/email-sdk, recorded October 23, 2026. APIs and setup may differ in the Bijection adaptation.
One TypeScript client for transactional email. Pick the providers you actually send through, add retries and fallback routes, catch unsupported fields before they are silently dropped, and keep every send observable.
- Adapters for 22 provider APIs plus SMTP, 23 adapters total, behind one normalized message
- Retries within an adapter, plus fallback routes across adapters
- Fail-fast field-support checks before a provider drops data
- Batch personalization with per-recipient variables, plus provider-side scheduled sends
- Observability hooks for logs, metrics, and traces
- Test adapters that never call real providers
- CLI for adapter discovery, doctor checks, and dry-run sends
Install
npm install @opencoredev/email-sdk
The SDK is server-side only and needs Node 20+ or Bun. Keep provider API keys out of client code.
Usage
import { createEmailClient } from "@opencoredev/email-sdk";
import { resend } from "@opencoredev/email-sdk/resend";
const email = createEmailClient({
adapters: [resend({ apiKey: process.env.RESEND_API_KEY! })],
});
await email.send({
from: "Acme <hello@acme.com>",
to: "user@example.com",
subject: "Welcome",
html: "<p>It works.</p>",
});
Adapters
Resend, Postmark, SendGrid, AWS SES, Mailgun, Brevo, MailerSend, SparkPost, Mailchimp, Iterable, Loops, Plunk, Mailtrap, Cloudflare, Unosend, Scaleway, ZeptoMail, MailPace, Sequenzy, JetEmail, Lettermint, Primitive, SMTP, and a testing adapter, each imported from its own entry point. New here? Start with resend for the fastest first send.
CLI
npx email-sdk doctor --adapter resend
Discover adapters, validate setup, and run dry-run smoke sends from any environment.
Documentation
Full docs live at email-sdk.dev/docs. Good places to start:
Telemetry
Email SDK collects anonymous usage analytics so we can see which adapters and CLI commands get used and how often sends succeed. The first run prints a notice with opt-out instructions.
What gets collected:
- Built-in adapter names (custom adapters are reported as
custom) and CLI command names - Success or failure, error codes, and send duration
- Total recipient counts (
to+cc+bcc) and whether a message includes attachments (a boolean only, never the files themselves) - Whether scheduling was requested
- SDK version, OS, Node.js version, whether the run happens in CI (and which CI provider), and whether usage comes from the library or the bundled CLI
- Redacted error reports: the error type, the Email SDK error code, and stack traces with file paths reduced to package-relative names. Error messages are scrubbed of email addresses, URLs, quoted text, long tokens, and home directories before upload.
Everything is tied to a random anonymous ID stored in ~/.config/email-sdk/telemetry.json. Email content, subjects, addresses, headers, attachments, API keys, and any other message data are never collected.
Opt out at any time with an environment variable:
export EMAIL_SDK_TELEMETRY=0 # or DO_NOT_TRACK=1
or per client in code:
const client = createEmailClient({ adapters: [resend({ apiKey })], telemetry: false });
Telemetry is also disabled automatically when NODE_ENV=test.
Sponsors
Email SDK is supported by companies that help keep provider integrations practical and maintained. Want your logo here? Become a sponsor →