# API reference

> Every Pidgely endpoint, generated from the OpenAPI 3.1 document, with parameters, request examples in six languages, responses and errors.

Source: https://docs.pidgely.com/api-reference/

The Pidgely API is a JSON REST API at `https://api.pidgely.com`. Every page in this section is generated at build time from the [OpenAPI 3.1 document](https://docs.pidgely.com/openapi.yaml) (also as [JSON](https://docs.pidgely.com/openapi.json)), so it always matches the deployed contract.

- **Authentication:** `Authorization: Bearer pdg_…` ([Authentication](https://docs.pidgely.com/authentication/))
- **Errors:** `{"statusCode", "name", "message"}` ([Errors](https://docs.pidgely.com/errors/))
- **Lists:** `limit`, `after`, `before` → `{"object": "list", "has_more", "data"}` ([Pagination](https://docs.pidgely.com/pagination/))
- **Retries:** `Idempotency-Key` on sends ([Idempotency](https://docs.pidgely.com/idempotency/))
- **Timestamps:** `YYYY-MM-DD HH:MM:SS.ffffff+00` in UTC

Request examples show the call in each [official SDK](https://docs.pidgely.com/sdks/) (Node.js, Python, PHP, Go, Ruby; preview) and the raw request in cURL.

The **native API** (`/v1/…`) predates the main routes and is documented for completeness (cURL examples only); prefer the main endpoints and the SDKs for new code. Dashboard (cookie session) and operator endpoints are internal and not covered here.

## Emails

| Endpoint | Description |
|---|---|
| [`POST /emails`](https://docs.pidgely.com/api-reference/emails/send/) | Send an email |
| [`POST /emails/batch`](https://docs.pidgely.com/api-reference/emails/send-batch/) | Send a batch of emails |
| [`GET /emails`](https://docs.pidgely.com/api-reference/emails/list/) | List emails |
| [`GET /emails/{id}`](https://docs.pidgely.com/api-reference/emails/retrieve/) | Retrieve an email |
| [`PATCH /emails/{id}`](https://docs.pidgely.com/api-reference/emails/update/) | Reschedule an email |
| [`POST /emails/{id}/cancel`](https://docs.pidgely.com/api-reference/emails/cancel/) | Cancel a scheduled email |
| [`GET /emails/{email_id}/attachments`](https://docs.pidgely.com/api-reference/emails/list-attachments/) | List an email's attachments |
| [`GET /emails/{email_id}/attachments/{id}`](https://docs.pidgely.com/api-reference/emails/retrieve-attachment/) | Retrieve an attachment |

## Domains

| Endpoint | Description |
|---|---|
| [`POST /domains`](https://docs.pidgely.com/api-reference/domains/create/) | Create a domain |
| [`GET /domains`](https://docs.pidgely.com/api-reference/domains/list/) | List domains |
| [`GET /domains/{id}`](https://docs.pidgely.com/api-reference/domains/retrieve/) | Retrieve a domain |
| [`PATCH /domains/{id}`](https://docs.pidgely.com/api-reference/domains/update/) | Update a domain |
| [`DELETE /domains/{id}`](https://docs.pidgely.com/api-reference/domains/delete/) | Delete a domain |
| [`POST /domains/{id}/verify`](https://docs.pidgely.com/api-reference/domains/verify/) | Verify a domain's DNS records |

## API keys

| Endpoint | Description |
|---|---|
| [`POST /api-keys`](https://docs.pidgely.com/api-reference/api-keys/create/) | Create an API key |
| [`GET /api-keys`](https://docs.pidgely.com/api-reference/api-keys/list/) | List API keys |
| [`PATCH /api-keys/{id}`](https://docs.pidgely.com/api-reference/api-keys/update/) | Rename an API key |
| [`DELETE /api-keys/{id}`](https://docs.pidgely.com/api-reference/api-keys/delete/) | Delete an API key |

## Webhooks

| Endpoint | Description |
|---|---|
| [`POST /webhooks`](https://docs.pidgely.com/api-reference/webhooks/create/) | Create a webhook |
| [`GET /webhooks`](https://docs.pidgely.com/api-reference/webhooks/list/) | List webhooks |
| [`GET /webhooks/{id}`](https://docs.pidgely.com/api-reference/webhooks/retrieve/) | Retrieve a webhook |
| [`PATCH /webhooks/{id}`](https://docs.pidgely.com/api-reference/webhooks/update/) | Update a webhook |
| [`DELETE /webhooks/{id}`](https://docs.pidgely.com/api-reference/webhooks/delete/) | Delete a webhook |
| [`POST /webhooks/{id}/signing-secret/rotate`](https://docs.pidgely.com/api-reference/webhooks/rotate-secret/) | Rotate a signing secret |

## Templates

| Endpoint | Description |
|---|---|
| [`POST /templates`](https://docs.pidgely.com/api-reference/templates/create/) | Create a template |
| [`GET /templates`](https://docs.pidgely.com/api-reference/templates/list/) | List templates |
| [`GET /templates/{key}`](https://docs.pidgely.com/api-reference/templates/retrieve/) | Retrieve a template (draft) |
| [`PATCH /templates/{key}`](https://docs.pidgely.com/api-reference/templates/update/) | Update a template draft |
| [`DELETE /templates/{key}`](https://docs.pidgely.com/api-reference/templates/delete/) | Delete a template |
| [`POST /templates/{key}/preview`](https://docs.pidgely.com/api-reference/templates/preview/) | Preview a template |
| [`POST /templates/{key}/publish`](https://docs.pidgely.com/api-reference/templates/publish/) | Publish a template |
| [`POST /templates/{key}/duplicate`](https://docs.pidgely.com/api-reference/templates/duplicate/) | Duplicate a template |

## Contacts

| Endpoint | Description |
|---|---|
| [`POST /contacts`](https://docs.pidgely.com/api-reference/contacts/create/) | Create a contact |
| [`GET /contacts`](https://docs.pidgely.com/api-reference/contacts/list/) | List contacts |
| [`GET /contacts/{key}`](https://docs.pidgely.com/api-reference/contacts/retrieve/) | Retrieve a contact |
| [`PATCH /contacts/{key}`](https://docs.pidgely.com/api-reference/contacts/update/) | Update a contact (unsubscribed syncs the suppression list) |
| [`DELETE /contacts/{key}`](https://docs.pidgely.com/api-reference/contacts/delete/) | Delete a contact |
| [`POST /contacts/batch`](https://docs.pidgely.com/api-reference/contacts/post-batch/) | Upsert contacts in batch |
| [`GET /contacts/{key}/segments`](https://docs.pidgely.com/api-reference/contacts/list-segments/) | List a contact's segments |
| [`POST /contacts/{key}/segments/{segment_id}`](https://docs.pidgely.com/api-reference/contacts/add-segment/) | Add a contact to a segment |
| [`DELETE /contacts/{key}/segments/{segment_id}`](https://docs.pidgely.com/api-reference/contacts/remove-segment/) | Remove a contact from a segment |

## Segments

| Endpoint | Description |
|---|---|
| [`POST /segments`](https://docs.pidgely.com/api-reference/segments/create/) | Create a segment |
| [`GET /segments`](https://docs.pidgely.com/api-reference/segments/list/) | List segments |
| [`GET /segments/{id}`](https://docs.pidgely.com/api-reference/segments/retrieve/) | Retrieve a segment |
| [`PATCH /segments/{id}`](https://docs.pidgely.com/api-reference/segments/update/) | Rename a segment |
| [`DELETE /segments/{id}`](https://docs.pidgely.com/api-reference/segments/delete/) | Delete a segment |
| [`GET /segments/{id}/contacts`](https://docs.pidgely.com/api-reference/segments/list-contacts/) | List a segment's contacts |

## Broadcasts

| Endpoint | Description |
|---|---|
| [`POST /broadcasts`](https://docs.pidgely.com/api-reference/broadcasts/create/) | Create a broadcast |
| [`GET /broadcasts`](https://docs.pidgely.com/api-reference/broadcasts/list/) | List broadcasts |
| [`GET /broadcasts/{id}`](https://docs.pidgely.com/api-reference/broadcasts/retrieve/) | Retrieve a broadcast |
| [`PATCH /broadcasts/{id}`](https://docs.pidgely.com/api-reference/broadcasts/update/) | Update a draft broadcast |
| [`DELETE /broadcasts/{id}`](https://docs.pidgely.com/api-reference/broadcasts/delete/) | Delete a broadcast |
| [`POST /broadcasts/{id}/send`](https://docs.pidgely.com/api-reference/broadcasts/send/) | Send a broadcast |
| [`POST /broadcasts/{id}/cancel`](https://docs.pidgely.com/api-reference/broadcasts/cancel/) | Cancel a broadcast |
| [`POST /broadcasts/{id}/duplicate`](https://docs.pidgely.com/api-reference/broadcasts/duplicate/) | Duplicate a broadcast |

## Suppressions

| Endpoint | Description |
|---|---|
| [`POST /suppressions`](https://docs.pidgely.com/api-reference/suppressions/create/) | Add a suppression |
| [`GET /suppressions`](https://docs.pidgely.com/api-reference/suppressions/list/) | List suppressions |
| [`GET /suppressions/{id}`](https://docs.pidgely.com/api-reference/suppressions/retrieve/) | Retrieve a suppression |
| [`DELETE /suppressions/{id}`](https://docs.pidgely.com/api-reference/suppressions/delete/) | Remove a suppression |
| [`POST /suppressions/batch/add`](https://docs.pidgely.com/api-reference/suppressions/batch-add/) | Add suppressions in batch |
| [`POST /suppressions/batch/remove`](https://docs.pidgely.com/api-reference/suppressions/batch-remove/) | Remove suppressions in batch |

## Audiences (legacy)

| Endpoint | Description |
|---|---|
| [`POST /audiences`](https://docs.pidgely.com/api-reference/audiences/create/) | Create an audience |
| [`GET /audiences`](https://docs.pidgely.com/api-reference/audiences/list/) | List audiences |
| [`GET /audiences/{id}`](https://docs.pidgely.com/api-reference/audiences/retrieve/) | Retrieve an audience |
| [`DELETE /audiences/{id}`](https://docs.pidgely.com/api-reference/audiences/delete/) | Delete an audience |
| [`GET /audiences/{id}/contacts`](https://docs.pidgely.com/api-reference/audiences/list-contacts/) | List an audience's contacts |
| [`POST /audiences/{id}/contacts`](https://docs.pidgely.com/api-reference/audiences/add-contact/) | Create a contact in an audience |
| [`GET /audiences/{id}/contacts/{key}`](https://docs.pidgely.com/api-reference/audiences/retrieve-contact/) | Retrieve a contact |
| [`PATCH /audiences/{id}/contacts/{key}`](https://docs.pidgely.com/api-reference/audiences/update-contact/) | Update a contact |
| [`DELETE /audiences/{id}/contacts/{key}`](https://docs.pidgely.com/api-reference/audiences/remove-contact/) | Delete a contact |

## Native API (v1)

| Endpoint | Description |
|---|---|
| [`POST /v1/api-keys`](https://docs.pidgely.com/api-reference/v1/api-keys/create/) | Create an API key |
| [`GET /v1/api-keys`](https://docs.pidgely.com/api-reference/v1/api-keys/list/) | List API keys |
| [`DELETE /v1/api-keys/{id}`](https://docs.pidgely.com/api-reference/v1/api-keys/delete/) | Revoke an API key |
| [`POST /v1/domains`](https://docs.pidgely.com/api-reference/v1/domains/create/) | Create a domain |
| [`GET /v1/domains`](https://docs.pidgely.com/api-reference/v1/domains/list/) | List domains |
| [`GET /v1/domains/{id}`](https://docs.pidgely.com/api-reference/v1/domains/retrieve/) | Retrieve a domain |
| [`DELETE /v1/domains/{id}`](https://docs.pidgely.com/api-reference/v1/domains/delete/) | Delete a domain |
| [`POST /v1/domains/{id}/verify`](https://docs.pidgely.com/api-reference/v1/domains/verify/) | Verify DNS now |
| [`POST /v1/emails`](https://docs.pidgely.com/api-reference/v1/emails/send/) | Send an email |
| [`POST /v1/emails/batch`](https://docs.pidgely.com/api-reference/v1/emails/send-batch/) | Send up to 100 emails atomically |
| [`GET /v1/emails`](https://docs.pidgely.com/api-reference/v1/emails/list/) | List emails |
| [`GET /v1/emails/{id}`](https://docs.pidgely.com/api-reference/v1/emails/retrieve/) | Retrieve an email with deliveries |
| [`POST /v1/emails/{id}/cancel`](https://docs.pidgely.com/api-reference/v1/emails/cancel/) | Cancel a scheduled email |
| [`POST /v1/suppressions`](https://docs.pidgely.com/api-reference/v1/suppressions/create/) | Add a suppression |
| [`GET /v1/suppressions`](https://docs.pidgely.com/api-reference/v1/suppressions/list/) | List suppressions |
| [`DELETE /v1/suppressions/{address}`](https://docs.pidgely.com/api-reference/v1/suppressions/delete/) | Remove a suppression |
| [`GET /v1/usage`](https://docs.pidgely.com/api-reference/v1/usage/retrieve/) | Retrieve usage |
| [`POST /v1/webhooks`](https://docs.pidgely.com/api-reference/v1/webhooks/create/) | Create a webhook (native event names) |
| [`GET /v1/webhooks`](https://docs.pidgely.com/api-reference/v1/webhooks/list/) | List webhooks |
| [`DELETE /v1/webhooks/{id}`](https://docs.pidgely.com/api-reference/v1/webhooks/delete/) | Delete a webhook |