# Brevo

A Brevo component for Bijection.

- Package: @bijectionhq/brevo
- Category: Messaging
- Status: Preview
- License: Apache-2.0
- Bijection source (repository access required): https://github.com/bijectionhq/brevo/tree/258ecfc86afb596ee50f16d005a40f41d9053708
- Upstream: https://github.com/pierre-H/convex-brevo/tree/754bc2eed9c447a36e740f441cb130ac4d87a0c7
- Documentation: https://docs.bijection.com/components/using
- Directory: https://bijection.com/components/brevo

## Get the source

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

```sh
git clone https://github.com/bijectionhq/brevo.git
cd brevo
git checkout 258ecfc86afb596ee50f16d005a40f41d9053708
```

## 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.

## Upstream package documentation

Recorded 2026-10-23. This describes convex-brevo; check the Bijection adaptation separately.

The Brevo component provides durable transactional email and SMS delivery through Convex's queueing system. It integrates with Brevo's API endpoints for email and SMS, handles webhook-based status tracking, and provides rate-limited delivery with sandbox mode support. Developers get a fully managed email/SMS pipeline with status queries, cancellation, and retry capabilities built into their Convex backend.

### Use cases

• **Transactional emails** - Send order confirmations, password resets, and account notifications with template support and delivery tracking
• **SMS verification codes** - Deliver authentication codes and account validation messages with webhook-based status updates
• **Email campaigns with templates** - Use Brevo's template system with dynamic parameters for personalized messaging at scale
• **Reliable notification delivery** - Queue critical notifications with automatic retry logic and status monitoring for mission-critical communications
• **Development testing** - Test email and SMS flows in sandbox mode without sending real messages during development

### How it works

The component wraps Brevo's REST API endpoints (`/v3/smtp/email` and `/v3/transactionalSMS/send`) with Convex's durable execution model. You configure it with your Brevo API key and webhook secrets, then register it in `convex.config.ts` to make it available across your functions.

Email and SMS sending happens through the `sendEmail()` and `sendSms()` methods, which accept Brevo-native payloads including sender, recipients, content, and template parameters. The component queues these requests and handles rate limiting automatically while storing message status in internal Convex tables.

Webhook integration provides real-time status tracking by correlating Brevo's `message-id` values with your queued messages. You mount HTTP endpoints for `/brevo-webhook` and `/brevo-sms-webhook` that authenticate using shared secrets. The component provides status query methods like `status()` and `smsStatus()` plus cancellation capabilities for managing message delivery.

### Upstream README

# Brevo Convex Component

This component integrates Brevo transactional email and SMS with Convex.

## Features

- Durable queueing with Convex mutations and workpools
- Rate-limited Brevo delivery via `POST /v3/smtp/email`
- Rate-limited Brevo delivery via `POST /v3/transactionalSMS/send`
- Brevo-native payloads: `sender`, `to`, `templateId`, `params`, `htmlContent`,
  `textContent`
- Transactional SMS payloads: `sender`, `recipient`, `content`, `tag`
- `sandboxMode` support via `X-Sib-Sandbox: drop`
- Webhook-driven status tracking using Brevo `message-id`
- Email status queries, cancellation, and manual-send fallback
- SMS status queries, cancellation, and manual-send fallback

## Configuration

Set these environment variables in Convex:

- `BREVO_API_KEY`
- `BREVO_WEBHOOK_SECRET`
- `BREVO_SMS_WEBHOOK_BASE_URL` (optional)
- `BREVO_SMS_WEBHOOK_SECRET` (optional, defaults to `BREVO_WEBHOOK_SECRET`)

Register the component in `convex/convex.config.ts`:

```ts
import { defineApp } from "convex/server";
import brevo from "convex-brevo/convex.config.js";

const app = defineApp();
app.use(brevo);

export default app;
```

## Usage

```ts
import { components } from "./_generated/api";
import { Brevo } from "convex-brevo";

export const brevo = new Brevo(components.brevo, {
  sandboxMode: true,
  smsWebhookBaseUrl: process.env.BREVO_SMS_WEBHOOK_BASE_URL,
});

await brevo.sendEmail(ctx, {
  sender: { email: "sender@example.com", name: "Sender" },
  to: [{ email: "recipient@example.com", name: "Recipient" }],
  subject: "Hello from Brevo",
  htmlContent: "<p>It works.</p>",
  tags: ["welcome"],
});
```

Template example:

```ts
await brevo.sendEmail(ctx, {
  sender: { email: "sender@example.com", name: "Sender" },
  to: [{ email: "recipient@example.com" }],
  templateId: 42,
  params: {
    FIRST_NAME: "Ada",
    ORDER_ID: 1234,
  },
});
```

SMS example:

```ts
await brevo.sendSms(ctx, {
  sender: "MyShop",
  recipient: "33680065433",
  content: "Enter this code: CAAA08",
  tag: "accountValidation",
});
```

## Webhooks

Mount an HTTP endpoint and protect it with the shared secret.

```ts
import { httpRouter } from "convex/server";
import { httpAction } from "./_generated/server";
import { brevo } from "./mail";

const http = httpRouter();

http.route({
  path: "/brevo-webhook",
  method: "POST",
  handler: httpAction(async (ctx, req) => {
    return await brevo.handleBrevoEventWebhook(ctx, req);
  }),
});

http.route({
  path: "/brevo-sms-webhook",
  method: "POST",
  handler: httpAction(async (ctx, req) => {
    return await brevo.handleBrevoSmsWebhook(ctx, req);
  }),
});

export default http;
```

The handler accepts the secret in either:

- query param `?secret=...`
- header `x-webhook-secret`

Brevo IP whitelisting is still recommended.

For SMS tracking, set `smsWebhookBaseUrl` so the component can attach a
per-message `webUrl` to Brevo SMS sends.

## Status API

```ts
const emailId = await brevo.sendEmail(ctx, { ... });
const status = await brevo.status(ctx, emailId);
const fullEmail = await brevo.get(ctx, emailId);
await brevo.cancelEmail(ctx, emailId);

const smsId = await brevo.sendSms(ctx, { ... });
const smsStatus = await brevo.smsStatus(ctx, smsId);
const fullSms = await brevo.getSms(ctx, smsId);
await brevo.cancelSms(ctx, smsId);
```

## Manual sends

Use `sendEmailManually` or `sendSmsManually` when you need a custom Brevo call
while still storing status in the component tables.

## Notes

- `sandboxMode` validates requests without sending real email.
- The current implementation keeps the Convex queueing architecture and uses
  durable single-message Brevo API calls.
- Emails are correlated through Brevo `message-id` values stored in the
  component tables.
- SMS events are correlated either through the generated `smsId` in the webhook
  URL or by Brevo `messageId` fallback when no `smsWebhookBaseUrl` is used.

## Legal disclaimer

This project is an unofficial community integration. It is not affiliated, associated, authorized, endorsed by, or in any way officially connected with Brevo SAS. "Brevo" is a registered trademark belonging to its respective owners.