Skip to content
Pidgely Docs

API reference

API reference

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

View as Markdown

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 (also as JSON), so it always matches the deployed contract.

  • Authentication: Authorization: Bearer pdg_… (Authentication)
  • Errors: {"statusCode", "name", "message"} (Errors)
  • Lists: limit, after, before → {"object": "list", "has_more", "data"} (Pagination)
  • Retries: Idempotency-Key on sends (Idempotency)
  • Timestamps: YYYY-MM-DD HH:MM:SS.ffffff+00 in UTC

Request examples show the call in each official SDK (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 Send an email
POST /emails/batch Send a batch of emails
GET /emails List emails
GET /emails/{id} Retrieve an email
PATCH /emails/{id} Reschedule an email
POST /emails/{id}/cancel Cancel a scheduled email
GET /emails/{email_id}/attachments List an email's attachments
GET /emails/{email_id}/attachments/{id} Retrieve an attachment

Domains

Endpoint Description
POST /domains Create a domain
GET /domains List domains
GET /domains/{id} Retrieve a domain
PATCH /domains/{id} Update a domain
DELETE /domains/{id} Delete a domain
POST /domains/{id}/verify Verify a domain's DNS records

API keys

Endpoint Description
POST /api-keys Create an API key
GET /api-keys List API keys
PATCH /api-keys/{id} Rename an API key
DELETE /api-keys/{id} Delete an API key

Webhooks

Endpoint Description
POST /webhooks Create a webhook
GET /webhooks List webhooks
GET /webhooks/{id} Retrieve a webhook
PATCH /webhooks/{id} Update a webhook
DELETE /webhooks/{id} Delete a webhook
POST /webhooks/{id}/signing-secret/rotate Rotate a signing secret

Templates

Endpoint Description
POST /templates Create a template
GET /templates List templates
GET /templates/{key} Retrieve a template (draft)
PATCH /templates/{key} Update a template draft
DELETE /templates/{key} Delete a template
POST /templates/{key}/preview Preview a template
POST /templates/{key}/publish Publish a template
POST /templates/{key}/duplicate Duplicate a template

Contacts

Endpoint Description
POST /contacts Create a contact
GET /contacts List contacts
GET /contacts/{key} Retrieve a contact
PATCH /contacts/{key} Update a contact (unsubscribed syncs the suppression list)
DELETE /contacts/{key} Delete a contact
POST /contacts/batch Upsert contacts in batch
GET /contacts/{key}/segments List a contact's segments
POST /contacts/{key}/segments/{segment_id} Add a contact to a segment
DELETE /contacts/{key}/segments/{segment_id} Remove a contact from a segment

Segments

Endpoint Description
POST /segments Create a segment
GET /segments List segments
GET /segments/{id} Retrieve a segment
PATCH /segments/{id} Rename a segment
DELETE /segments/{id} Delete a segment
GET /segments/{id}/contacts List a segment's contacts

Broadcasts

Endpoint Description
POST /broadcasts Create a broadcast
GET /broadcasts List broadcasts
GET /broadcasts/{id} Retrieve a broadcast
PATCH /broadcasts/{id} Update a draft broadcast
DELETE /broadcasts/{id} Delete a broadcast
POST /broadcasts/{id}/send Send a broadcast
POST /broadcasts/{id}/cancel Cancel a broadcast
POST /broadcasts/{id}/duplicate Duplicate a broadcast

Suppressions

Endpoint Description
POST /suppressions Add a suppression
GET /suppressions List suppressions
GET /suppressions/{id} Retrieve a suppression
DELETE /suppressions/{id} Remove a suppression
POST /suppressions/batch/add Add suppressions in batch
POST /suppressions/batch/remove Remove suppressions in batch

Audiences (legacy)

Endpoint Description
POST /audiences Create an audience
GET /audiences List audiences
GET /audiences/{id} Retrieve an audience
DELETE /audiences/{id} Delete an audience
GET /audiences/{id}/contacts List an audience's contacts
POST /audiences/{id}/contacts Create a contact in an audience
GET /audiences/{id}/contacts/{key} Retrieve a contact
PATCH /audiences/{id}/contacts/{key} Update a contact
DELETE /audiences/{id}/contacts/{key} Delete a contact

Native API (v1)

Endpoint Description
POST /v1/api-keys Create an API key
GET /v1/api-keys List API keys
DELETE /v1/api-keys/{id} Revoke an API key
POST /v1/domains Create a domain
GET /v1/domains List domains
GET /v1/domains/{id} Retrieve a domain
DELETE /v1/domains/{id} Delete a domain
POST /v1/domains/{id}/verify Verify DNS now
POST /v1/emails Send an email
POST /v1/emails/batch Send up to 100 emails atomically
GET /v1/emails List emails
GET /v1/emails/{id} Retrieve an email with deliveries
POST /v1/emails/{id}/cancel Cancel a scheduled email
POST /v1/suppressions Add a suppression
GET /v1/suppressions List suppressions
DELETE /v1/suppressions/{address} Remove a suppression
GET /v1/usage Retrieve usage
POST /v1/webhooks Create a webhook (native event names)
GET /v1/webhooks List webhooks
DELETE /v1/webhooks/{id} Delete a webhook