sendpigeon

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

Install

``bash
npm install sendpigeon
`

Quick Start

`typescript
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: "

Welcome aboard.

",
});

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:

`tsx
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: ,
});
`

Requires @react-email/render as peer dependency:

`bash
npm install @react-email/render
`

Configuration

`typescript
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:

`bash


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):

`typescript
const { data } = await pigeon.send({
from: "hello@yourdomain.com",
to: "user@example.com",
subject: "Welcome!",
html: "

Check out our site!

",
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

`typescript
// 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

`typescript
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