---
name: bijection-usesend
description: "Evaluate and integrate the Usesend component with Bijection."
---

# Usesend

The Bijection useSend Component - send emails durably with batching, rate limiting, and webhook support.

- Package: @bijectionhq/usesend
- Category: Messaging
- Status: Preview
- License: Apache-2.0
- Bijection source (repository access required): https://github.com/bijectionhq/usesend/tree/fe4f6c88d49622ef258bd33298b0bb36645e25f7
- Upstream: https://github.com/pulgueta/usesend-convex/tree/07d1c9a81ab64c3e828f58ac875b700ddba71a01
- Documentation: https://docs.bijection.com/components/using
- Directory: https://bijection.com/components/usesend

## Get the source

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

```sh
git clone https://github.com/bijectionhq/usesend.git
cd usesend
git checkout fe4f6c88d49622ef258bd33298b0bb36645e25f7
```

## 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 @pulgueta/usesend-convex. 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 useSend. Follow the installation and configuration steps exactly.

# useSend

## Instructions

useSend Convex Component integrates the useSend transactional email service (an open-source Resend alternative) into Convex applications with durable, exactly-once email delivery. It uses Convex workpools for retry logic, automatic batching to the useSend batch endpoint, and idempotency key management to prevent duplicate sends. Webhook support enables real-time delivery status callbacks, and a typed REST client exposes the full useSend API for contacts, domains, campaigns, and analytics.

### Installation

```bash
npm install @pulgueta/usesend-convex
```

Current npm version: `@pulgueta/usesend-convex@0.3.0`

## Use cases

- Sending transactional emails (signup confirmation, password reset) with guaranteed delivery even if the useSend API is temporarily unavailable
- Queuing large volumes of marketing or notification emails without hitting rate limits, relying on automatic batching and backoff
- Tracking per-email delivery status (delivered, bounced, spam complaint) by wiring up a webhook handler and an `onEmailEvent` callback mutation
- Using React Email components to author templates server-side, rendering to HTML and plain-text fallback before enqueueing through the durable send pipeline
- Managing contacts, contact books, campaigns, and domain verification through a typed REST client from within Convex actions

## How it works

After installing the package and adding `app.use(usesend)` in `convex.config.ts`, you instantiate `UseSend` with `components.usesend` and optionally pass a `UseSendOptions` object for API key, base URL, retry settings, and an `onEmailEvent` callback. Calling `usesend.sendEmail(ctx, { from, to, subject, html })` from any mutation enqueues the email into the component's internal queue, which batches and forwards sends to the useSend `/emails/batch` endpoint via Convex workpools, handling retries with configurable backoff.

The `sendEmail` method returns an `EmailId` you can use to check status via `usesend.status(ctx, emailId)` or cancel a waiting email via `usesend.cancelEmail(ctx, emailId)`. Status fields include `delivered`, `bounced`, `failed`, `complained`, `opened`, and `clicked`.

Webhook integration is set up by mounting an HTTP route in `convex/http.ts` that delegates to `usesend.handleUseSendEventWebhook(ctx, req)`. Setting the `USESEND_WEBHOOK_SECRET` environment variable enables signature verification. When an event arrives, the component calls the registered `onEmailEvent` internal mutation with the email ID and event type.

The full useSend REST API is available through `usesend.api`, covering emails, contacts, contact books, domains, campaigns, and analytics. These methods make HTTP calls and must run inside Convex actions. Data retention is not automatic; you are expected to schedule `cleanupOldEmails` and `cleanupAbandonedEmails` via a cron job to remove finalized email records.

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

## Resources

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