API reference

HTTPS JSON at /api. Send Authorization: Bearer plus a pg_ key. Paste a key below to fill the curl examples, then copy a request.

API key for examples

Paste a pg_ key. Curl samples on this page update, including Copy. Run sends the sample to this Pigeon instance and shows the live status and body.

Sending keys may call email endpoints. Domain routes need a full-access key. Each address in to, cc, and bcc counts as one email against the quota. More than 10 requests in a second returns 429. filter.transaction_id pauses a burst from one person or to one address, and filter.admin keeps mail flowing to an admin.

Errors

Failures use statusCode, name, and message. 401 is a missing or invalid key. 403 is a quota, a sending-only key on a privileged route, or a paused account. 422 is validation. 429 filter_stopped means a filter key is temporarily paused.

JSON
{
  "statusCode": 401,
  "name": "missing_api_key",
  "message": "Missing or invalid API key. Send Authorization: Bearer pg_..."
}

Emails

POST /api/emails

Send or schedule one message. from must use a verified domain, or a from address you verified on Domains. Omit scheduled_at to send now. segment_id sends to every subscribed contact in that segment instead of to. template is a published slug; drafts are not sent. locale picks the translation when that slug exists in more than one language. Optional filter.transaction_id pauses a burst from one person or to one address. filter.admin keeps mail flowing to an admin.

Request

curl
curl -X POST https://pigeonfs.com/api/emails \
  -H "Authorization: Bearer pg_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Ada <ada@yourdomain.com>",
    "to": ["person@example.com"],
    "subject": "Welcome",
    "html": "<p>Hello</p>",
    "scheduled_at": "2026-10-01T09:00:00"
  }'

Example · 201

JSON
{
  "id": "0f8c2a1e-6b3d-4c9a-9e21-2b7d1c4e8a10",
  "from": "Ada <ada@yourdomain.com>",
  "to": ["person@example.com"],
  "cc": [],
  "bcc": [],
  "reply_to": [],
  "subject": "Welcome",
  "html": "<p>Hello</p>",
  "text": null,
  "status": "scheduled",
  "scheduled_at": "2026-10-01T09:00:00Z",
  "created_at": "2026-09-28T21:04:11Z"
}
GET /api/emails

List recent mail. Omit direction for outbound. direction=inbound lists replies stored on Receiving. Filter with status and q on the query string. Each row includes text and omits html.

Request

curl
curl "https://pigeonfs.com/api/emails?direction=inbound" \
  -H "Authorization: Bearer pg_your_api_key"

Example · 200

JSON
{
  "data": [
    {
      "id": "0f8c2a1e-6b3d-4c9a-9e21-2b7d1c4e8a10",
      "from": "Pat <person@example.com>",
      "to": ["ada@yourdomain.com"],
      "subject": "Re: Welcome",
      "text": "Yes please",
      "status": "delivered",
      "scheduled_at": null,
      "created_at": "2026-09-28T21:04:11Z"
    }
  ]
}
GET /api/emails/:id

Read one email, including html and text.

Request

curl
curl https://pigeonfs.com/api/emails/0f8c2a1e-6b3d-4c9a-9e21-2b7d1c4e8a10 \
  -H "Authorization: Bearer pg_your_api_key"

Example · 200

JSON
{
  "id": "0f8c2a1e-6b3d-4c9a-9e21-2b7d1c4e8a10",
  "from": "Ada <ada@yourdomain.com>",
  "to": ["person@example.com"],
  "cc": [],
  "bcc": [],
  "reply_to": [],
  "subject": "Welcome",
  "html": "<p>Hello</p>",
  "text": null,
  "status": "sent",
  "scheduled_at": null,
  "created_at": "2026-09-28T21:04:11Z"
}
POST /api/emails/:id/cancel

Cancel a message that is still queued or scheduled.

Request

curl
curl -X POST https://pigeonfs.com/api/emails/0f8c2a1e-6b3d-4c9a-9e21-2b7d1c4e8a10/cancel \
  -H "Authorization: Bearer pg_your_api_key"

Example · 200

JSON
{
  "id": "0f8c2a1e-6b3d-4c9a-9e21-2b7d1c4e8a10",
  "status": "canceled",
  "subject": "Welcome"
}

Domains

These routes need a full-access key. A sending key returns 403.

GET /api/domains

List domains and the DNS records to publish.

Request

curl
curl https://pigeonfs.com/api/domains \
  -H "Authorization: Bearer pg_your_api_key"

Example · 200

JSON
{
  "data": [
    {
      "id": "2c91aa00-1b44-4e0c-9d77-11a0b3c8d201",
      "name": "yourdomain.com",
      "status": "verified",
      "region": "us-east-1",
      "records": []
    }
  ]
}
POST /api/domains

Add a sending domain. region defaults to us-east-1.

Request

curl
curl -X POST https://pigeonfs.com/api/domains \
  -H "Authorization: Bearer pg_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "yourdomain.com", "region": "us-east-1"}'

Example · 201

JSON
{
  "id": "2c91aa00-1b44-4e0c-9d77-11a0b3c8d201",
  "name": "yourdomain.com",
  "status": "pending",
  "region": "us-east-1",
  "records": []
}
POST /api/domains/:id/verify

Check DNS and mark the domain verified when the records are in place.

Request

curl
curl -X POST https://pigeonfs.com/api/domains/2c91aa00-1b44-4e0c-9d77-11a0b3c8d201/verify \
  -H "Authorization: Bearer pg_your_api_key"

Example · 200

JSON
{
  "id": "2c91aa00-1b44-4e0c-9d77-11a0b3c8d201",
  "name": "yourdomain.com",
  "status": "verified",
  "region": "us-east-1"
}
DELETE /api/domains/:id

Remove a domain. The response body is empty.

Request

curl
curl -X DELETE https://pigeonfs.com/api/domains/2c91aa00-1b44-4e0c-9d77-11a0b3c8d201 \
  -H "Authorization: Bearer pg_your_api_key"

Example · 204

Empty body.

Audience and automations

POST /api/contacts

Add a contact. email is required. name is optional.

Request

curl
curl -X POST https://pigeonfs.com/api/contacts \
  -H "Authorization: Bearer pg_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"email": "ada@example.net", "name": "Ada Lovelace"}'

Example · 201

JSON
{
  "id": "9a14d0c2-5e88-4b1f-8c33-0d6e2a91f704",
  "email": "ada@example.net",
  "name": "Ada Lovelace"
}
POST /api/automations/:id/trigger

Run an automation. Body: to, optional subject, and optional variables.

Request

curl
curl -X POST https://pigeonfs.com/api/automations/4e7b91aa-0c12-4d55-a901-7f3c28b19e44/trigger \
  -H "Authorization: Bearer pg_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"to": "person@example.com", "variables": {"name": "Ada"}}'

Example · 200

JSON
{
  "id": "0f8c2a1e-6b3d-4c9a-9e21-2b7d1c4e8a10",
  "to": ["person@example.com"],
  "subject": "Welcome Ada",
  "status": "sent"
}

Newsletters

GET /api/newsletters

List newsletters on this account, newest first.

Request

curl
curl https://pigeonfs.com/api/newsletters \
  -H "Authorization: Bearer pg_your_api_key"

Example · 200

JSON
{
  "data": [
    {
      "id": "6d1c0a40-2b55-4e18-9a77-0c4e8b21f901",
      "name": "Sunday Notes",
      "slug": "k3m9qp",
      "from": "Ada <ada@yourdomain.com>",
      "design": "paper",
      "url": "https://pigeonfs.com/n/k3m9qp",
      "confirmed": 12
    }
  ]
}
POST /api/newsletters

Create a newsletter. name and from are required. design is paper, butter, ink, sea, tomato, linen, night, postcard, ledger, bloom, signal, harbor, or folio. The page link is six characters and is not shared with another account.

Request

curl
curl -X POST https://pigeonfs.com/api/newsletters \
  -H "Authorization: Bearer pg_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Sunday Notes", "from": "Ada <ada@yourdomain.com>", "design": "butter"}'

Example · 201

JSON
{
  "id": "6d1c0a40-2b55-4e18-9a77-0c4e8b21f901",
  "name": "Sunday Notes",
  "slug": "k3m9qp",
  "design": "butter",
  "url": "https://pigeonfs.com/n/k3m9qp",
  "embed_url": "https://pigeonfs.com/n/k3m9qp/embed"
}
POST /api/newsletters/:id/campaigns

Draft an issue. name, subject, and html are required. Set scheduled_at in the future to wait.

Request

curl
curl -X POST https://pigeonfs.com/api/newsletters/6d1c0a40-2b55-4e18-9a77-0c4e8b21f901/campaigns \
  -H "Authorization: Bearer pg_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Issue 1", "subject": "Hello", "html": "<p>Hello</p>"}'

Example · 201

JSON
{
  "id": "8b22e014-7c30-4a55-91d0-2e6f0a18c774",
  "newsletter_id": "6d1c0a40-2b55-4e18-9a77-0c4e8b21f901",
  "name": "Issue 1",
  "subject": "Hello",
  "status": "draft"
}
POST /api/newsletters/:id/campaigns/:campaign_id/publish

Send the issue to confirmed readers. A future schedule stays scheduled. A sent issue returns 422.

Request

curl
curl -X POST https://pigeonfs.com/api/newsletters/6d1c0a40-2b55-4e18-9a77-0c4e8b21f901/campaigns/8b22e014-7c30-4a55-91d0-2e6f0a18c774/publish \
  -H "Authorization: Bearer pg_your_api_key"

Example · 200

JSON
{
  "sent": 12,
  "skipped": 0,
  "stopped": null,
  "status": "sent"
}

Marketing audiences

These lists belong to the team on the API key. email is required. attributes.last_access is a timestamp. Other attribute keys are custom. A signup webhook adds the contact to the audience, then enrolls active campaigns for that list.

POST /api/audiences

Create a named audience. webhook_secret is returned once. The first list, or default: true, is the project default for POST /api/events.

Request

curl
curl -X POST https://pigeonfs.com/api/audiences \
  -H "Authorization: Bearer pg_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Trial users"}'

Example · 201

JSON
{
  "id": "3c91aa00-1b44-4e0c-9d77-11a0b3c8d301",
  "name": "Trial users",
  "default": true,
  "webhook_secret": "whsec_...",
  "contacts": 0
}
POST /api/audiences/:id/contacts

Create or merge a contact by email or external_id. last_access is typed. Other keys stay on attributes.

Request

curl
curl -X POST https://pigeonfs.com/api/audiences/3c91aa00-1b44-4e0c-9d77-11a0b3c8d301/contacts \
  -H "Authorization: Bearer pg_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"email":"ada@example.net","external_id":"usr_1","attributes":{"last_access":"2026-10-01T09:00:00Z","plan":"pro"}}'

Example · 201

JSON
{
  "id": "9a14d0c2-5e88-4b1f-8c33-0d6e2a91f804",
  "email": "ada@example.net",
  "external_id": "usr_1",
  "attributes": {
    "last_access": "2026-10-01T09:00:00Z",
    "plan": "pro"
  }
}
POST /api/audiences/:id/imports

Import up to 1,000 contacts. The response is a job with status counts.

Request

curl
curl -X POST https://pigeonfs.com/api/audiences/3c91aa00-1b44-4e0c-9d77-11a0b3c8d301/imports \
  -H "Authorization: Bearer pg_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"contacts":[{"email":"ada@example.net"}]}'

Example · 202

JSON
{
  "id": "7e22e014-7c30-4a55-91d0-2e6f0a18c801",
  "status": "completed",
  "imported": 1,
  "updated": 0,
  "failed": 0
}
POST /api/audiences/:id/events

Signup webhook for one contact. Optional HMAC: X-Pigeon-Timestamp and X-Pigeon-Signature of sha256(timestamp + '.' + body). Optional X-Pigeon-Idempotency-Key. Older occurred_at values are ignored. A new contact is enrolled in matching active campaigns.

Request

curl
curl -X POST https://pigeonfs.com/api/audiences/3c91aa00-1b44-4e0c-9d77-11a0b3c8d301/events \
  -H "Authorization: Bearer pg_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"email":"ada@example.net","occurred_at":"2026-10-27T15:00:00Z","consented":true,"attributes":{"last_access":"2026-10-27T15:00:00Z"}}'

Example · 201

JSON
{
  "email": "ada@example.net",
  "consented": true,
  "marketing_subscribed": true,
  "unsubscribed": false,
  "ignored": false,
  "duplicate": false
}
POST /api/events

Same signup webhook without the audience in the path. audience_id in the body selects the list. Omit it to use the project's default audience.

Request

curl
curl -X POST https://pigeonfs.com/api/events \
  -H "Authorization: Bearer pg_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"email":"ada@example.net","audience_id":"3c91aa00-1b44-4e0c-9d77-11a0b3c8d301"}'

Example · 201

JSON
{
  "email": "ada@example.net",
  "ignored": false,
  "duplicate": false
}