sendpigeon

Official Node.js SDK for SendPigeon - transactional email API.

Install

npm install sendpigeon

Quick Start

import { SendPigeon } from "sendpigeon";

const pigeon = new SendPigeon("sp_live_your_api_key");

const { data, error } = await pigeon.send({
  from: "hello@yourdomain.com",
  to: "user@example.com",
  subject: "Hello!",
  html: "<p>Welcome aboard.</p>",
});

if (error) {
  console.error(error.message);
  // error.code: "api_error" | "network_error" | "timeout_error"
  // error.apiCode: "QUOTA_EXCEEDED" | "DOMAIN_NOT_VERIFIED" | ...
  // error.status: 402
} else {
  console.log(data.id); // "em_abc123"
}

React Email

Use React Email components directly:

import { SendPigeon } from "sendpigeon";
import { WelcomeEmail } from "./emails/welcome";

const { data, error } = await pigeon.send({
  from: "hello@yourdomain.com",
  to: "user@example.com",
  subject: "Welcome!",
  react: <WelcomeEmail name="John" />,
});

Requires @react-email/render as peer dependency:

npm install @react-email/render

Configuration

const pigeon = new SendPigeon("sp_live_your_api_key", {
  timeout: 30000,   // request timeout in ms (default: 30s)
  maxRetries: 2,    // retry on 429/5xx (default: 2, max: 5, 0 to disable)
  debug: true,      // log requests/responses to console
});

Retries use exponential backoff and respect Retry-After headers.

Local Development

Use @sendpigeon-sdk/cli to catch emails locally:

# Terminal 1: Start local server
npx @sendpigeon-sdk/cli dev

# Terminal 2: Run your app with dev mode
SENDPIGEON_DEV=true npm run dev

When SENDPIGEON_DEV=true, the SDK routes requests to localhost:4100 instead of production.

Tracking

Enable open/click tracking per email (opt-in):

const { data } = await pigeon.send({
  from: "hello@yourdomain.com",
  to: "user@example.com",
  subject: "Welcome!",
  html: "<p>Check out our <a href='https://example.com'>site</a>!</p>",
  tracking: {
    opens: true,   // Track opens via invisible pixel
    clicks: true,  // Track link clicks
  },
});

// Response may include warnings if tracking is disabled at org level
if (data.warnings) {
  console.log("Warnings:", data.warnings);
}

Configure organization defaults in Settings → Tracking.

Available Methods

// Send emails
pigeon.send(email)
pigeon.sendBatch(emails)

// Email status
pigeon.emails.get(id)
pigeon.emails.cancel(id)

// Templates
pigeon.templates.list()
pigeon.templates.create(data)
pigeon.templates.get(id)
pigeon.templates.update(id, data)
pigeon.templates.delete(id)

// Domains
pigeon.domains.list()
pigeon.domains.create({ name })
pigeon.domains.get(id)
pigeon.domains.verify(id)
pigeon.domains.delete(id)

// API Keys
pigeon.apiKeys.list()
pigeon.apiKeys.create({ name, mode?, permission? })
pigeon.apiKeys.delete(id)

Webhook Verification

import { verifyWebhook, verifyInboundWebhook } from "sendpigeon";

// Outbound events (delivered, bounced, complained)
const result = await verifyWebhook({ payload, signature, timestamp, secret });

// Inbound emails
const result = await verifyInboundWebhook({ payload, signature, timestamp, secret });

Documentation

Full documentation with examples: sendpigeon.dev/docs

License

MIT