# Sequenzy (/docs/adapters/sequenzy)



<ProviderBadge adapter="sequenzy" />

Sequenzy is a sponsor-backed product-led email adapter for transactional sends. It supports direct content, template slugs, metadata variables, one reply-to address, URL attachments, and Base64 attachments, but not CC, BCC, headers, or tags.

## Before live sends [#before-live-sends]

Create a Sequenzy API key and verify the sender domain or sender address you plan to use in `from`. Run the local API auth check before sending from a new environment:

```bash
SEQUENZY_API_KEY="seq_live_..." bun run live:sequenzy
```

That command checks the authenticated account context. It does not send email unless you explicitly set `SEQUENZY_LIVE_SEND=true` with a test sender and recipient.

## Configure [#configure]

```ts
import { createEmailClient } from "@opencoredev/email-sdk";
import { sequenzy } from "@opencoredev/email-sdk/sequenzy";

const email = createEmailClient({
  adapters: [sequenzy({ apiKey: process.env.SEQUENZY_API_KEY! })],
});
```

## Send [#send]

```ts
const result = await email.send({
  from: "Acme <hello@acme.com>",
  to: [{ email: "user@example.com", name: "Ada" }],
  subject: "Welcome",
  html: "<p>Your workspace is ready.</p>",
  replyTo: "support@acme.com",
  metadata: {
    firstName: "Ada",
    workspaceName: "Acme",
  },
});

console.log(result.provider, result.messageId);
```

Sequenzy accepts one provider `body` value. When both `html` and `text` are present, the adapter sends `html`; omit `html` when the Sequenzy route should send a plain-text body.

Sequenzy maps flat `metadata` values to `variables`. Reserved metadata keys are mapped to provider fields instead:

| Metadata key                                             | Sequenzy field         |
| -------------------------------------------------------- | ---------------------- |
| `sequenzySlug`                                           | `slug`                 |
| `sequenzyPreview`                                        | `preview`              |
| `subscriberExternalId` or `sequenzySubscriberExternalId` | `subscriberExternalId` |

## Send with a template slug [#send-with-a-template-slug]

```ts
await email.send({
  from: "Acme <hello@acme.com>",
  to: "user@example.com",
  subject: "Welcome",
  html: "<p>Fallback body for local validation.</p>",
  metadata: {
    sequenzySlug: "welcome-workspace",
    firstName: "Ada",
    workspaceName: "Acme",
  },
});
```

When `metadata.sequenzySlug` is present, the adapter sends a Sequenzy template request. The `subject`, `html`, and `text` fields stay useful for local Email SDK validation, but the provider payload uses the template slug and variables. Generic metadata keys like `slug` and `preview` remain variables so fallback routes do not accidentally change behavior.

## Send with attachments [#send-with-attachments]

```ts
await email.send({
  from: "Acme <hello@acme.com>",
  to: "user@example.com",
  subject: "Export ready",
  html: "<p>Your export is attached.</p>",
  attachments: [
    {
      filename: "export.txt",
      content: "name,total\nAda,42",
      contentType: "text/plain",
    },
    {
      filename: "invoice.pdf",
      path: "https://cdn.example.com/invoices/inv_123.pdf",
    },
  ],
});
```

URL attachments are sent as Sequenzy `path` values. Local file and in-memory attachments are encoded as Base64 `content`.

## Options [#options]

| Option    | Type           | Required | Notes                                          |
| --------- | -------------- | -------- | ---------------------------------------------- |
| `apiKey`  | `string`       | Yes      | Sequenzy API key.                              |
| `baseUrl` | `string`       | No       | Defaults to `https://api.sequenzy.com/api/v1`. |
| `fetch`   | `typeof fetch` | No       | Useful for tests or custom runtimes.           |

## Response [#response]

The adapter maps Sequenzy `jobId` to the normalized `id` and `messageId` fields, maps returned recipients to `accepted`, and keeps the provider response in `raw`.

## Field support [#field-support]

Sequenzy maps one or more `to` recipients, `from`, `subject`, HTML/text body, one `replyTo`, flat metadata variables, template slugs, preview text, subscriber external IDs, and attachments. It rejects CC, BCC, headers, tags, and multiple reply-to addresses before the API call.

Because Sequenzy has one body field, HTML takes priority over text when both content fields are present.

See <a href="/docs/adapters/field-support">field support</a> before using Sequenzy in a fallback route.

## CLI smoke test [#cli-smoke-test]

```bash
SEQUENZY_API_KEY="seq_live_..." npx --yes --package @opencoredev/email-sdk email-sdk send \
  --adapter sequenzy \
  --from "Acme <hello@acme.com>" \
  --to user@example.com \
  --subject "Sequenzy test" \
  --text "It works"
```