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.
{ "statusCode": 401, "name": "missing_api_key", "message": "Missing or invalid API key. Send Authorization: Bearer pg_..." }
Emails
/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 -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
{ "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" }
/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 "https://pigeonfs.com/api/emails?direction=inbound" \ -H "Authorization: Bearer pg_your_api_key"
Example · 200
{ "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" } ] }
/api/emails/:id
Read one email, including html and text.
Request
curl https://pigeonfs.com/api/emails/0f8c2a1e-6b3d-4c9a-9e21-2b7d1c4e8a10 \ -H "Authorization: Bearer pg_your_api_key"
Example · 200
{ "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" }
/api/emails/:id/cancel
Cancel a message that is still queued or scheduled.
Request
curl -X POST https://pigeonfs.com/api/emails/0f8c2a1e-6b3d-4c9a-9e21-2b7d1c4e8a10/cancel \ -H "Authorization: Bearer pg_your_api_key"
Example · 200
{ "id": "0f8c2a1e-6b3d-4c9a-9e21-2b7d1c4e8a10", "status": "canceled", "subject": "Welcome" }
Domains
These routes need a full-access key. A sending key returns 403.
/api/domains
List domains and the DNS records to publish.
Request
curl https://pigeonfs.com/api/domains \ -H "Authorization: Bearer pg_your_api_key"
Example · 200
{ "data": [ { "id": "2c91aa00-1b44-4e0c-9d77-11a0b3c8d201", "name": "yourdomain.com", "status": "verified", "region": "us-east-1", "records": [] } ] }
/api/domains
Add a sending domain. region defaults to us-east-1.
Request
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
{ "id": "2c91aa00-1b44-4e0c-9d77-11a0b3c8d201", "name": "yourdomain.com", "status": "pending", "region": "us-east-1", "records": [] }
/api/domains/:id/verify
Check DNS and mark the domain verified when the records are in place.
Request
curl -X POST https://pigeonfs.com/api/domains/2c91aa00-1b44-4e0c-9d77-11a0b3c8d201/verify \ -H "Authorization: Bearer pg_your_api_key"
Example · 200
{ "id": "2c91aa00-1b44-4e0c-9d77-11a0b3c8d201", "name": "yourdomain.com", "status": "verified", "region": "us-east-1" }
/api/domains/:id
Remove a domain. The response body is empty.
Request
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
/api/contacts
Add a contact. email is required. name is optional.
Request
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
{ "id": "9a14d0c2-5e88-4b1f-8c33-0d6e2a91f704", "email": "ada@example.net", "name": "Ada Lovelace" }
/api/automations/:id/trigger
Run an automation. Body: to, optional subject, and optional variables.
Request
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
{ "id": "0f8c2a1e-6b3d-4c9a-9e21-2b7d1c4e8a10", "to": ["person@example.com"], "subject": "Welcome Ada", "status": "sent" }
Newsletters
/api/newsletters/:id/campaigns
Draft an issue. name, subject, and html are required. Set scheduled_at in the future to wait.
Request
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
{ "id": "8b22e014-7c30-4a55-91d0-2e6f0a18c774", "newsletter_id": "6d1c0a40-2b55-4e18-9a77-0c4e8b21f901", "name": "Issue 1", "subject": "Hello", "status": "draft" }
/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 -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
{ "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.
/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 -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
{ "id": "3c91aa00-1b44-4e0c-9d77-11a0b3c8d301", "name": "Trial users", "default": true, "webhook_secret": "whsec_...", "contacts": 0 }
/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 -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
{ "id": "9a14d0c2-5e88-4b1f-8c33-0d6e2a91f804", "email": "ada@example.net", "external_id": "usr_1", "attributes": { "last_access": "2026-10-01T09:00:00Z", "plan": "pro" } }
/api/audiences/:id/imports
Import up to 1,000 contacts. The response is a job with status counts.
Request
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
{ "id": "7e22e014-7c30-4a55-91d0-2e6f0a18c801", "status": "completed", "imported": 1, "updated": 0, "failed": 0 }
/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 -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
{ "email": "ada@example.net", "consented": true, "marketing_subscribed": true, "unsubscribed": false, "ignored": false, "duplicate": false }
/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 -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
{ "email": "ada@example.net", "ignored": false, "duplicate": false }