---
name: bijection-convex-lettermint
description: "Evaluate and integrate the Lettermint component with Bijection."
---

# Lettermint

A Lettermint component for Convex.

This is an upstream package. It has not been adapted or qualified for Bijection.

- Package: convex-lettermint
- Source: https://github.com/pierre-H/convex-lettermint
- npm: https://www.npmjs.com/package/convex-lettermint
- Directory: https://bijection.com/components/convex-lettermint

Read the upstream README for setup, license, and compatibility before using it.

## 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 convex-lettermint. 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 Lettermint. Follow the installation and configuration steps exactly.

# Lettermint

## Instructions

convex-lettermint integrates the Lettermint transactional email service with Convex, providing a durable email queue backed by Convex workpools. Emails are batched to Lettermint's `/send/batch` endpoint with idempotency keys derived from internal Convex email IDs, and delivery events are tracked via verified HMAC-signed webhooks. The component handles rate limiting, retry backoff, and status tracking out of the box.

### Installation

```bash
npm install convex-lettermint
```

Current npm version: `convex-lettermint@1.0.1`

## Use cases

- Sending transactional emails (welcome, password reset, notifications) from Convex mutations or actions with durable retry guarantees
- Tracking email delivery lifecycle events (delivered, bounced, opened, clicked) by wiring Lettermint webhooks to a Convex HTTP endpoint
- Queuing high volumes of outbound emails without overwhelming the Lettermint API, using built-in rate limiting and batching
- Cancelling pending emails before they are dispatched, or checking per-email status including bounce and complaint flags
- Sending emails with attachments or inline images by bypassing the queue with `sendEmailManually` and calling the Lettermint API directly inside a Convex action

## How it works

After installing the package and adding `app.use(lettermint)` in `convex/convex.config.ts`, you instantiate a `Lettermint` client with `new Lettermint(components.lettermint, options)`. Calling `lettermint.sendEmail(ctx, params)` enqueues the message and returns a branded `EmailId`. The component batches queued messages to Lettermint's `/send/batch` endpoint, using the internal `EmailId` as the `Idempotency-Key` to prevent duplicate sends across retries.

Failed API calls are retried using Convex workpools with configurable `initialBackoffMs` and `retryAttempts` options. `testMode` defaults to `true`, restricting delivery to Lettermint test domain addresses until explicitly disabled in `LettermintOptions`.

Webhook events are handled by mounting an HTTP endpoint in `convex/http.ts` that calls `lettermint.handleLettermintEventWebhook(ctx, req)`. The component verifies the `X-Lettermint-Signature` HMAC-SHA256 header and rejects stale or invalid requests before routing events to your registered `onEmailEvent` mutation callback, which receives a typed `{ id: EmailId; event: EmailEvent }` argument.

Data retention is managed manually via `cleanupOldEmails` and `cleanupAbandonedEmails` functions exposed on the component, which can be scheduled from a Convex cron job. For emails requiring attachments or features outside the batch API, `sendEmailManually` accepts a callback that constructs and fires the raw Lettermint API request, while still recording the email in the component's tracking layer.

## 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 Lettermint is not needed

## Resources

- [npm package](https://www.npmjs.com/package/convex-lettermint)
- [GitHub repository](https://github.com/pierre-H/convex-lettermint)
- [Live demo](https://github.com/pierre-H/convex-lettermint)
- [Convex Components Directory](https://www.convex.dev/components/convex-lettermint)
- [Convex documentation](https://docs.convex.dev)