SparkPost Connector Guide

The SparkPost connector lets Tealfabric workflows send transactional and operational emails through SparkPost using API key authentication. This guide explains secure setup, practical send patterns, and reliability controls for production messaging.

When to use this connector

Use this connector when workflows need to send confirmation emails, alert notifications, or operational messages at runtime. It supports send, receive (message events and other GET resources), sync, batch, and test. Standardizing sender identity improves consistency across teams.

Prerequisites

Before configuring the integration, create a SparkPost API key with the minimum permissions needed for transmission operations. Verify your sender domain or sender address so requests are accepted in production. Confirm deliverability setup, including SPF and DKIM, before scaling automated traffic.

Configuration reference

Connector settings are stored in integration configuration and reused during execution. Keep credentials secure and rotate API keys on schedule.

• api_key (required for test): SparkPost API key sent in the Authorization header.
• from_email (required for test): Default verified sender email; may be overridden per send call with from or from_email.
• from_name (optional): Default display name for sender identity.
• base_url (optional): SparkPost API URL, default https://api.sparkpost.com/api/v1.
• timeout_seconds (optional): Request timeout for API calls, default 30.

test validates api_key and from_email before calling GET /account. Other operations do not require full configuration up front; send still needs a valid API key and recipient payload at runtime.

Send transactional email

The send operation posts to SparkPost POST /transmissions. Include both HTML and plain text when possible to improve compatibility across clients.

const baseUrl = "https://api.example.com/api/v1";
const tenantId = "<TENANT_ID>";
const apiKey = "<API_KEY>";

type SparkPostSendResult = {
  success: boolean;
  data?: {
    message_count: number;
    transmission_id: string | null;
    total_accepted_recipients: number | null;
    data: {
      results?: {
        id?: string;
        total_accepted_recipients?: number;
      };
    };
  };
};

async function sendWelcomeEmail(integrationId: string): Promise<SparkPostSendResult> {
  const response = await fetch(
    `${baseUrl}/integrations/${encodeURIComponent(integrationId)}/execute`,
    {
      method: "POST",
      headers: {
        "X-API-Key": apiKey,
        "X-Tenant-ID": tenantId,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        operation: "send",
        to: "recipient@example.com",
        subject: "Welcome to the platform",
        html: "<h1>Welcome</h1><p>Your account is ready.</p>",
        text: "Welcome\n\nYour account is ready.",
      }),
    }
  );

  if (!response.ok) throw new Error(`Request failed: ${response.status}`);
  return (await response.json()) as SparkPostSendResult;
}

curl -X POST "https://api.example.com/api/v1/integrations/<ENTITY_ID>/execute" \
  -H "X-API-Key: <API_KEY>" \
  -H "X-Tenant-ID: <TENANT_ID>" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "send",
    "to": "recipient@example.com",
    "subject": "Welcome to the platform",
    "html": "<h1>Welcome</h1><p>Your account is ready.</p>",
    "text": "Welcome\n\nYour account is ready."
  }'

{
  "success": true,
  "data": {
    "message_count": 1,
    "transmission_id": "<TRANSMISSION_ID>",
    "total_accepted_recipients": 1,
    "data": {
      "results": {
        "total_accepted_recipients": 1,
        "id": "<TRANSMISSION_ID>"
      }
    }
  }
}

Receive message events

Use receive to query SparkPost resources such as message-events. Defaults to message-events when endpoint and resource are omitted.

curl -X POST "https://api.example.com/api/v1/integrations/<ENTITY_ID>/execute" \
  -H "X-API-Key: <API_KEY>" \
  -H "X-Tenant-ID: <TENANT_ID>" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "receive",
    "endpoint": "message-events",
    "query": {
      "events": "delivery"
    }
  }'

{
  "success": true,
  "data": {
    "message_count": 2,
    "total_size": 2,
    "data": [
      { "event": "delivery", "rcpt_to": "recipient@example.com" }
    ]
  }
}

Validate and troubleshoot

Run test after key rotation, sender identity changes, or API URL updates. Most failures are caused by invalid API keys, unverified sender domains, or rate-limit pressure during high-volume sends.

curl -X POST "https://api.example.com/api/v1/integrations/<ENTITY_ID>/execute" \
  -H "X-API-Key: <API_KEY>" \
  -H "X-Tenant-ID: <TENANT_ID>" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "test"
  }'

{
  "success": true,
  "data": {
    "message": "SparkPost connection test successful",
    "details": {
      "api_base_url": "https://api.sparkpost.com/api/v1"
    }
  }
}

Additional references

For endpoint-level options and template behavior, review SparkPost API documentation, the transmissions API reference, and message events API docs. Clear sender verification and event-query contracts help keep messaging workflows stable.