SparkPost

Send through the SparkPost Transmissions API with metadata, substitution data from tags, and a provider-side sandbox mode.

Capabilities

Repeated headers	Idempotency	Scheduling	Personalized
No	`none`	Yes	`expanded`

These values come from the adapter's exported capabilities declaration. The field support matrix covers normalized message fields.

The SparkPost adapter calls the SparkPost Transmissions API with plain fetch. Two things set it apart: a sandbox option that routes sends through SparkPost's shared sandbox domain for testing, and tags become SparkPost substitution_data as name: value pairs instead of a flat list.

SparkPost@opencoredev/email-sdk/sparkpost

Provider docs

Configure

Create an API key with Transmissions permission in the SparkPost dashboard. SparkPost expects the raw key in the Authorization header, so the adapter sends it without a Bearer prefix.

lib/email.ts

import { createEmailClient } from "@opencoredev/email-sdk";
import { sparkpost } from "@opencoredev/email-sdk/sparkpost";

export const email = createEmailClient({
  adapters: [sparkpost({ apiKey: process.env.SPARKPOST_API_KEY! })],
});

Prop

Type

Send

SparkPost maps replyTo, headers, attachments, metadata, and tags (each tag becomes a substitution_data entry keyed by its name). sendAt schedules the transmission natively as options.start_time; SparkPost accepts at most 3 days in the future.

const result = await email.send({
  from: { email: "alerts@acme.com", name: "Acme Alerts" },
  to: "user@example.com",
  replyTo: "support@acme.com",
  subject: "Usage alert: 90% of plan limit",
  html: "<p>Your workspace is at 90% of its monthly quota.</p>",
  metadata: { workspaceId: "ws_123" },
  tags: [{ name: "type", value: "usage-alert" }],
});

console.log(result.id); // SparkPost transmission id

The response id is the transmission id from results.id (or results.transmission_id). Use it to query SparkPost's events API for delivery status.

No cc or bcc

This adapter sends one flat recipient list, so cc or bcc on a message throws an EmailValidationError before any request is made. Add extra recipients to to, or pick a cc/bcc-capable adapter.

Verify from the CLI

SPARKPOST_API_KEY="..." npx --package @opencoredev/email-sdk email-sdk doctor --adapter sparkpost

SPARKPOST_API_KEY="..." npx --package @opencoredev/email-sdk email-sdk send \
  --adapter sparkpost \
  --from "Acme <hello@acme.com>" \
  --to user@example.com \
  --subject "SparkPost smoke test" \
  --text "It works" \
  --dry-run

Drop --dry-run for one real send, or set sandbox: true in code first to exercise the API through SparkPost's shared sandbox domain before touching your own.

Frequently asked questions

Does Email SDK support SparkPost?

Yes. Email SDK ships a SparkPost adapter imported from @opencoredev/email-sdk/sparkpost. You keep your SparkPost account and credentials; the SDK adds message validation, typed errors, and no-network test adapters around the same send() call used for every other provider.

Which message fields does the SparkPost adapter support?

SparkPost supports Reply-To address, Custom headers, Attachments, Tags, Metadata, and Scheduled sending (sendAt). It does not support CC recipients and BCC recipients; Email SDK rejects a message that uses those fields before any request is made.

Can SparkPost schedule email for later with Email SDK?

Yes. Set sendAt on the message and the SparkPost adapter passes the scheduled time to the provider.

Does the SparkPost adapter support idempotent sends?

No. SparkPost has no provider-side idempotency, so a retried send can be delivered twice. Deduplicate in your own queue before retrying.