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.

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.

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. 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.

Request

curl

curl -X POST https://pigeon.bitscorp.co/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 outbound mail. Filter with status and q on the query string.

Request

curl

curl "https://pigeon.bitscorp.co/api/emails?status=sent&q=Welcome" \
  -H "Authorization: Bearer pg_your_api_key"

Example · 200

JSON

{
  "data": [
    {
      "id": "0f8c2a1e-6b3d-4c9a-9e21-2b7d1c4e8a10",
      "from": "Ada <ada@yourdomain.com>",
      "to": ["person@example.com"],
      "subject": "Welcome",
      "status": "sent",
      "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://pigeon.bitscorp.co/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://pigeon.bitscorp.co/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://pigeon.bitscorp.co/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://pigeon.bitscorp.co/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://pigeon.bitscorp.co/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://pigeon.bitscorp.co/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://pigeon.bitscorp.co/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://pigeon.bitscorp.co/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"
}