SparkPost

Capabilities

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.

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! })],
});

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.

Verify from the CLI

SPARKPOST_API_KEY="..." npx email-sdk doctor --adapter sparkpost

SPARKPOST_API_KEY="..." npx 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.