---
name: bijection-sweego
description: "Evaluate and integrate the Sweego component with Bijection."
---

# Sweego

A Sweego email & SMS component for Bijection.

- Package: @bijectionhq/sweego
- Category: Messaging
- Status: Preview
- License: Apache-2.0
- Bijection source (repository access required): https://github.com/bijectionhq/sweego/tree/28ed56e43a0ebd5dd590d08359f6a863901646de
- Upstream: https://github.com/christian-ek/sweego/tree/c8ad9fb508d8ff6f759d26b735c939037889355e
- Documentation: https://docs.bijection.com/components/using
- Directory: https://bijection.com/components/sweego

## Get the source

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

```sh
git clone https://github.com/bijectionhq/sweego.git
cd sweego
git checkout 28ed56e43a0ebd5dd590d08359f6a863901646de
```

## 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 @christian-ek/sweego. 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 Sweego. Follow the installation and configuration steps exactly.

# Sweego

## Instructions

Sweego is a Convex component that sends transactional email and SMS through the Sweego REST API with durable background delivery via a workpool. It handles automatic retries on transient failures (429s, 5xx), records permanent failures without retrying, and maintains per-recipient delivery state updated through HMAC-SHA256 verified webhooks. The component covers the full Sweego send surface: templates, attachments, bulk personalized email, custom headers, and campaign metadata.

### Installation

```bash
npm install @christian-ek/sweego
```

Current npm version: `@christian-ek/sweego@0.4.1`

## Use cases

- Sending transactional emails (welcome, receipts, password resets) from mutations or actions with guaranteed delivery and automatic retry on transient API failures
- Tracking per-recipient delivery outcomes (delivered, bounced, opened, clicked, complained) via Sweego webhooks without building your own signature verification or event storage
- Sending transactional or marketing SMS with per-recipient region configuration and cost estimation before sending
- Running bulk personalized email campaigns with per-recipient template variable interpolation using Sweego-hosted templates
- Building an admin message log with paginated listing, full-text search over subjects and recipients, and status or tag filtering without mirroring sends into your own tables

## How it works

Install the package, set `SWEEGO_API_KEY` in your Convex deployment, and register the component in `convex/convex.config.ts` with `app.use(sweego)`. Instantiate `new Sweego(components.sweego, {})` in your server code and call `sendEmail`, `sendSms`, or `sendBulkEmail` from any mutation or action. Each call enqueues the message and returns a `MessageId` immediately; the component delivers it in the background using a workpool with configurable `retryAttempts` and `initialBackoffMs`.

Delivery tracking requires a webhook endpoint. Mount `sweego.handleSweegoWebhook(ctx, req)` on an HTTP route in `convex/http.ts`, point Sweego's dashboard at `https://<your-deployment>.convex.site/webhooks/sweego`, and set `SWEEGO_WEBHOOK_SECRET`. The component verifies the `webhook-id`, `webhook-timestamp`, and `webhook-signature` HMAC-SHA256 headers against the raw body using the Web Crypto API before updating delivery state. An optional `onEvent` mutation reference triggers your own internal mutation on each event.

Use `sweego.status(ctx, messageId)` to read current delivery state, `sweego.cancel(ctx, messageId)` to cancel a queued message, and `sweego.list` or `sweego.search` for paginated or full-text queries over the message log. For environments without webhooks, `sweego.refreshStatus(ctx, messageId)` polls Sweego's logs directly from an action. Schedule `cleanupOldMessages` and `cleanupAbandonedMessages` via cron jobs to manage data retention.

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

## Resources

- [npm package](https://www.npmjs.com/package/%40christian-ek%2Fsweego)
- [GitHub repository](https://github.com/christian-ek/sweego)
- [Live demo](https://sweego.christianek.io)
- [Convex Components Directory](https://www.convex.dev/components/christian-ek/sweego)
- [Convex documentation](https://docs.convex.dev)