---
name: bijection-email-sdk
description: "Evaluate and integrate the Email SDK component with Bijection."
---

# Email SDK

Provider-portable transactional email for Bijection with durable queues, retries, fallback adapters, idempotency, webhooks, and reactive status.

- Package: @bijectionhq/email-sdk
- Category: Messaging
- Status: Reference
- License: MIT
- Bijection source (repository access required): https://github.com/bijectionhq/email-sdk/tree/fe6ec67063930027228f021d6e67ca5cd5d6dbd1/packages/convex-email
- Upstream: https://github.com/opencoredev/email-sdk/tree/2f89fbc34630e75685a87f2497cff36378827970/packages/convex-email
- Documentation: https://docs.bijection.com/components/using
- Directory: https://bijection.com/components/email-sdk

## Get the source

Bijection repository access is required. Request access at https://bijection.com/contact.

```sh
git clone https://github.com/bijectionhq/email-sdk.git
cd email-sdk
git checkout fe6ec67063930027228f021d6e67ca5cd5d6dbd1
cd packages/convex-email
```

## Before using this component

Read the package README at the recorded revision for setup, dependencies, and API examples. Upstream documentation describes the original package and may differ from the Bijection adaptation. This is a source candidate for evaluation. Catalog inclusion does not establish npm availability or runtime qualification. Check compatibility with your SDK and deployment before adoption. External providers run their own compute.

## Integration workflow

1. Read the source README and package manifest at the recorded revision.
2. Confirm the required SDK, dependency availability, and runtime compatibility.
3. Follow the component's documented setup and configuration. Never invent an npm install command from a catalog package name.
4. Keep credentials in the project's existing secret store.
5. Follow the project's execution rules for verification and report what was actually checked.

## Original upstream skill

The following guidance describes @opencoredev/convex-email. Its installation commands and APIs refer to the upstream package. Evaluate compatibility with the Bijection source separately.


> Agents: read this skill fully before writing code that uses Email SDK. Follow the installation and configuration steps exactly.

# Email SDK

## Instructions

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.

### Installation

```bash
npm install @opencoredev/convex-email
```

Current npm version: `@opencoredev/convex-email@5.0.0`

## Use cases

- 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

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.

## When NOT to use

- When a simpler built-in solution exists for your specific use case
- If you are not using Convex as your backend
- When the functionality provided by Email SDK is not needed

## Resources

- [npm package](https://www.npmjs.com/package/%40opencoredev%2Fconvex-email)
- [GitHub repository](https://github.com/opencoredev/email-sdk)
- [Live demo](https://email-sdk.dev/)
- [Convex Components Directory](https://www.convex.dev/components/opencoredev/convex-email)
- [Convex documentation](https://docs.convex.dev)