API v1.0

SendPigeon Documentation

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

REST API

Direct HTTP access for non-Node environments.

Authentication

All requests require Bearer token in the Authorization header.

cURLbash

curl -X POST https://api.sendpigeon.dev/v1/emails \
  -H "Authorization: Bearer sp_live_your_api_key" \
  -H "Content-Type: application/json"

Send Email — POST /v1/emails

cURLbash

curl -X POST https://api.sendpigeon.dev/v1/emails \
  -H "Authorization: Bearer sp_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "hello@acme.com",
    "to": "user@example.com",
    "subject": "Your order shipped!",
    "html": "<h1>Order #1234</h1>",
    "replyTo": "support@acme.com"
  }'

Response

{
  "id": "em_abc123def456",
  "status": "sent",
  "suppressed": []
}

Status: scheduled, cancelled, pending, sent, delivered, bounced, complained, failed

Send with Attachment

cURLbash

curl -X POST https://api.sendpigeon.dev/v1/emails \
  -H "Authorization: Bearer sp_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "hello@acme.com",
    "to": "user@example.com",
    "subject": "Your invoice",
    "html": "<p>See attached.</p>",
    "attachments": [{
      "filename": "invoice.pdf",
      "content": "JVBERi0xLjQK..."
    }]
  }'

Use content (base64) or path (HTTPS URL). Max 7MB/file, 25MB total.

Send with Template

cURLbash

curl -X POST https://api.sendpigeon.dev/v1/emails \
  -H "Authorization: Bearer sp_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "hello@acme.com",
    "to": "user@example.com",
    "templateId": "tpl_abc123",
    "variables": {
      "name": "John",
      "company": "Acme Inc"
    }
  }'

Schedule Email

Add scheduled_at to delay sending (max 30 days).

cURLbash

curl -X POST https://api.sendpigeon.dev/v1/emails \
  -H "Authorization: Bearer sp_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "hello@acme.com",
    "to": "user@example.com",
    "subject": "Reminder",
    "html": "<p>Dont forget!</p>",
    "scheduled_at": "2025-06-15T10:00:00Z"
  }'

Cancel Scheduled Email

cURLbash

curl -X DELETE https://api.sendpigeon.dev/v1/emails/{id}/schedule \
  -H "Authorization: Bearer sp_live_xxx"

Headers

Header	Description
Idempotency-Key	Unique key to prevent duplicate sends. Same key returns cached response.

Get Email — GET /v1/emails/:id

cURLbash

curl https://api.sendpigeon.dev/v1/emails/em_abc123 \
  -H "Authorization: Bearer sp_live_xxx"

Responsejson

{
  "id": "em_abc123",
  "status": "delivered",
  "fromAddress": "hello@yourdomain.com",
  "toAddress": "user@example.com",
  "subject": "Welcome!",
  "tags": ["welcome"],
  "metadata": { "userId": "123" },
  "createdAt": "2025-01-15T10:00:00Z",
  "sentAt": "2025-01-15T10:00:01Z",
  "deliveredAt": "2025-01-15T10:00:02Z"
}

Batch Send — POST /v1/emails/batch

Send up to 100 emails in one request. Each is processed independently.

cURLbash

curl -X POST https://api.sendpigeon.dev/v1/emails/batch \
  -H "Authorization: Bearer sp_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "emails": [
      {
        "from": "hello@yourdomain.com",
        "to": "user1@example.com",
        "subject": "Hello 1",
        "html": "<p>Hi!</p>"
      },
      {
        "from": "hello@yourdomain.com",
        "to": "user2@example.com",
        "subject": "Hello 2",
        "html": "<p>Hi!</p>"
      }
    ]
  }'

Responsejson

{
  "data": [
    { "index": 0, "status": "sent", "id": "em_abc123" },
    { "index": 1, "status": "sent", "id": "em_def456" }
  ],
  "summary": { "total": 2, "sent": 2, "failed": 0 }
}

Domains

cURLbash

# List domains
curl https://api.sendpigeon.dev/v1/domains \
  -H "Authorization: Bearer sp_live_xxx"
# Create domain
curl -X POST https://api.sendpigeon.dev/v1/domains \
  -H "Authorization: Bearer sp_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "name": "mail.example.com" }'
# Get domain (includes DNS records)
curl https://api.sendpigeon.dev/v1/domains/dom_abc123 \
  -H "Authorization: Bearer sp_live_xxx"
# Verify domain
curl -X POST https://api.sendpigeon.dev/v1/domains/dom_abc123/verify \
  -H "Authorization: Bearer sp_live_xxx"
# Delete domain
curl -X DELETE https://api.sendpigeon.dev/v1/domains/dom_abc123 \
  -H "Authorization: Bearer sp_live_xxx"

Templates

cURLbash

# List templates
curl https://api.sendpigeon.dev/v1/templates \
  -H "Authorization: Bearer sp_live_xxx"
# Create template
curl -X POST https://api.sendpigeon.dev/v1/templates \
  -H "Authorization: Bearer sp_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "welcome-email",
    "subject": "Welcome {{name}}!",
    "html": "<p>Hello {{name}}</p>"
  }'
# Get template
curl https://api.sendpigeon.dev/v1/templates/tpl_abc123 \
  -H "Authorization: Bearer sp_live_xxx"
# Update template
curl -X PATCH https://api.sendpigeon.dev/v1/templates/tpl_abc123 \
  -H "Authorization: Bearer sp_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "subject": "New subject" }'
# Delete template
curl -X DELETE https://api.sendpigeon.dev/v1/templates/tpl_abc123 \
  -H "Authorization: Bearer sp_live_xxx"

API Keys

cURLbash

# List API keys
curl https://api.sendpigeon.dev/v1/api-keys \
  -H "Authorization: Bearer sp_live_xxx"
# Create API key
curl -X POST https://api.sendpigeon.dev/v1/api-keys \
  -H "Authorization: Bearer sp_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production",
    "mode": "live",
    "permission": "sending"
  }'
# Delete API key
curl -X DELETE https://api.sendpigeon.dev/v1/api-keys/key_abc123 \
  -H "Authorization: Bearer sp_live_xxx"