API v1.0

SendPigeon Documentation

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

CLI

Send emails, manage templates, view logs, and run a local dev server.

Full CLI for SendPigeon. Send emails from the terminal, manage templates with git-friendly pull/push, stream logs in real-time, and catch emails locally during development.

Installation

The CLI is available as an npm package. No global install needed.

Terminalbash

npx @sendpigeon-sdk/cli dev

Or install globally:

Terminalbash

npm install -g @sendpigeon-sdk/cli
sendpigeon dev

Available Commands

Command	Description
dev	Start local dev server (HTTP + SMTP)
send	Send an email
status	Check API key and account status
templates	List, pull, push templates
logs	View and stream email logs
webhooks	View config and test webhooks
domains	List and verify domains

Authentication

Set your API key via environment variable or pass it to any command:

Terminalbash

# Via environment variable
export SENDPIGEON_API_KEY=sk_live_xxx
sendpigeon status
# Or pass directly
sendpigeon status --api-key sk_live_xxx

sendpigeon send

Send emails directly from the terminal:

Terminalbash

# Send with HTML
sendpigeon send \
  --to user@example.com \
  --subject "Hello" \
  --html "<p>Hi there!</p>"
# Send with template
sendpigeon send \
  --to user@example.com \
  --template welcome \
  --var name=John \
  --var company=Acme

sendpigeon templates

Manage templates with git-friendly pull/push workflow:

Terminalbash

# List all templates
sendpigeon templates list
# Download to ./sendpigeon-templates/
sendpigeon templates pull
# Upload changes
sendpigeon templates push

Templates are stored as JSON + HTML files, perfect for version control.

sendpigeon logs

View email logs and stream in real-time:

Terminalbash

# Show recent emails
sendpigeon logs
# Filter by status
sendpigeon logs --status bounced
# Stream in real-time
sendpigeon logs tail

sendpigeon dev

Starts a local email catching server. Works with any language or framework via SMTP, plus automatic routing for SendPigeon SDK users.

Terminalbash

$ npx @sendpigeon-sdk/cli dev
SendPigeon Dev Server
  API:  http://localhost:4100/v1/emails
  UI:   http://localhost:4100
  SMTP: localhost:4125
Emails sent to this server will be caught and displayed in the UI.
Press Ctrl+C to stop.

Option	Default	Description
--port, -p	4100	HTTP port
--smtp-port	4125	SMTP port
--no-smtp	-	Disable SMTP server

You can also set the port via environment variable:

Terminalbash

PORT=3000 npx @sendpigeon-sdk/cli dev

SDK Integration

Set SENDPIGEON_DEV=true and the SDK automatically routes to localhost:

Terminalbash

# Terminal 1: Start the dev server
npx @sendpigeon-sdk/cli dev
# Terminal 2: Run your app with dev mode
SENDPIGEON_DEV=true npm run dev

Your code stays the same. The SDK detects the environment variable:

TypeScripttypescript

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

SMTP (Any Language)

The dev server runs an SMTP server on port 4125. Point any app to it:

Any Languagejavascript

// Node.js (Nodemailer)
const transporter = nodemailer.createTransport({
  host: "localhost",
  port: 4125,
  secure: false,
});
// Python
with smtplib.SMTP("localhost", 4125) as server:
    server.send_message(msg)
// Ruby (Rails)
config.action_mailer.smtp_settings = { address: "localhost", port: 4125 }

All emails appear in the web UI at localhost:4100.

Web UI

Open http://localhost:4100 to view caught emails:

See all emails with from, to, subject
Preview HTML and plain text content
Inspect headers and metadata
Clear all emails with one click

Package.json Scripts

Add convenience scripts for your team:

package.jsonjson

{
  "scripts": {
    "dev": "next dev",
    "dev:email": "sendpigeon dev",
    "dev:full": "concurrently \"npm run dev:email\" \"SENDPIGEON_DEV=true npm run dev\""
  },
  "devDependencies": {
    "@sendpigeon-sdk/cli": "^1.0.0",
    "concurrently": "^8.0.0"
  }
}

Now npm run dev:full starts both the email server and your app.

Custom Port

If port 4100 is in use, specify a different port:

Terminalbash

npx @sendpigeon-sdk/cli dev --port 4200

Then configure the SDK to use the custom port:

TypeScripttypescript

const pigeon = new SendPigeon("sp_test_xxx", {
  baseUrl: "http://localhost:4200"
});

Tip: Use the CLI alongside test API keys for complete isolation. Test keys ensure no real emails are ever sent, even if SENDPIGEON_DEV is accidentally unset.