API v1.0

SendPigeon Documentation

Everything you need to send transactional emails. SDKs for Node.js, Python, Go, PHP and REST API.

Test Mode

Capture and inspect emails without delivering. No external tools needed.

Built-in sandbox. Two ways to test: local dev server (offline) or test API keys (cloud). No external services or account setup required.

Option 1: Local Dev Server

Catch emails locally during development. Works offline, zero config, instant feedback.

Terminalbash

# Start the local email catcher
npx @sendpigeon-sdk/cli dev
# Server running at http://localhost:4100

Then point your app to the local server:

Terminalbash

# Set environment variable
SENDPIGEON_DEV=true npm run dev

The SDK auto-detects dev mode and routes emails to localhost:

TypeScripttypescript

import { SendPigeon } from "sendpigeon";
const pigeon = new SendPigeon("sp_test_xxx");
// When SENDPIGEON_DEV=true, emails go to localhost:4100
await pigeon.send({
  from: "hello@yourdomain.com",
  to: "user@example.com",
  subject: "Test email",
  html: "<p>Caught locally!</p>"
});
// Console: [SendPigeon] Dev mode → http://localhost:4100

View emails: Open http://localhost:4100 in your browser to see caught emails with full HTML preview.

Option 2: Test API Keys

Use test keys for staging environments or CI/CD. Emails are captured in your dashboard, visible to your whole team.

Test vs Live Keys

API keys have two modes. Test keys capture emails without sending. Live keys send for real.

Key Prefix	Behavior
sp_test_xxx	Emails captured in dashboard, not delivered
sp_live_xxx	Emails sent to real recipients

Using Test Mode

Use a test key in development. Same code, same API — just no real emails sent.

TypeScripttypescript

import { SendPigeon } from "sendpigeon";
// Use test key in development
const pigeon = new SendPigeon(
  process.env.NODE_ENV === "production"
    ? "sp_live_xxx"
    : "sp_test_xxx"
);
// This email is captured, not sent
const { data } = await pigeon.send({
  from: "hello@yourdomain.com",
  to: "user@example.com",
  subject: "Welcome!",
  html: "<p>Hello!</p>",
});
console.log(data.id); // em_abc123 — view in dashboard

Inspecting Test Emails

All test emails appear in your dashboard under Sent Emails. You can:

View full email content (HTML and plain text)
Check recipient addresses, subject, and custom headers
Verify attachments were included correctly
Filter by status, domain, or search by recipient
Click any email to see complete details

Test emails show a Test badge so you can distinguish them from live emails.

CI/CD Integration

Use test keys in your test suite. Emails are captured but not sent, so you can verify email logic without side effects.

TypeScripttypescript

// jest.setup.ts
process.env.SENDPIGEON_API_KEY = "sp_test_xxx";
// your-test.spec.ts
it("sends welcome email on signup", async () => {
  await signup({ email: "test@example.com" });
  // Email was "sent" (captured) — no real delivery
  // Check your dashboard or use the API to verify
});

Quota: Test emails count toward your monthly quota. Retention: Same log retention as live emails (3-30 days based on plan).