# Pidgely Docs

> Pidgely is an email API for developers that delivers through its own MTA (pre-launch, early access). Base URL https://api.pidgely.com, official SDKs for Node.js (`pidgely`), Python, PHP, Go and Ruby (preview), SMTP relay (smtp.pidgely.com), signed webhooks (Standard Webhooks), templates, contacts, segments and broadcasts. Teams moving from Resend: see the migration guide.

Every page below is plain Markdown (append `.md` to any docs URL). The OpenAPI 3.1 document is the source of truth for the HTTP API.

- Base URL: https://api.pidgely.com
- Auth: `Authorization: Bearer pdg_<prefix>_<secret>`
- OpenAPI: https://docs.pidgely.com/openapi.yaml (also https://docs.pidgely.com/openapi.json)
- Everything in one file: https://docs.pidgely.com/llms-full.txt
- Product site: https://pidgely.com

## Get started

- [Introduction](https://docs.pidgely.com/index.md): Pidgely is an email API for developers that delivers through its own MTA. Official SDKs for Node.js, Python, PHP, Go and Ruby, SMTP relay and signed webhooks.
- [Quickstart](https://docs.pidgely.com/quickstart.md): Create an API key, verify your domain and send your first email with Pidgely in about two minutes, with the official SDKs or cURL.
- [Authentication](https://docs.pidgely.com/authentication.md): Authenticate with API keys sent as Bearer tokens. Choose full_access or sending_access, and restrict sending keys to a single domain.
- [Errors](https://docs.pidgely.com/errors.md): Error responses have the shape {statusCode, name, message}. The full list of error names, their HTTP status and how to handle them.
- [Rate limits & quotas](https://docs.pidgely.com/rate-limits.md): The API allows 10 requests per second per account by default. Plans set daily and monthly sending quotas; deliveries are paced per account.
- [Idempotency](https://docs.pidgely.com/idempotency.md): Send an Idempotency-Key with POST /emails and /emails/batch to retry safely. The response is replayed for 24 hours; a different body with the same key gets 409.
- [Pagination](https://docs.pidgely.com/pagination.md): List endpoints use cursor pagination with limit, after and before, and return {object, has_more, data}, newest first.

## Guides

- [Domains & DNS](https://docs.pidgely.com/guides/domains.md): Add a sending domain and publish its DKIM, return-path (MX + SPF) and DMARC records. How verification works and how to fix the usual DNS problems.
- [Sending email](https://docs.pidgely.com/guides/sending.md): Everything about POST /emails - recipients, HTML and text, batch sends, scheduling with natural language, attachments (base64 or remote path), tags, headers and streams.
- [Templates](https://docs.pidgely.com/guides/templates.md): Store email content once with typed variables and fallbacks, edit drafts safely, publish versions and send with template id or alias.
- [Contacts, segments & audiences](https://docs.pidgely.com/guides/contacts.md): Store contacts with typed properties, group them in segments for broadcasts, and keep unsubscribes in sync with the suppression list. Legacy audiences are supported.
- [Broadcasts](https://docs.pidgely.com/guides/broadcasts.md): Send campaigns to a segment with personalization variables, the {{{PIDGELY_UNSUBSCRIBE_URL}}} link and RFC 8058 one-click unsubscribe.
- [Webhooks](https://docs.pidgely.com/guides/webhooks.md): Receive signed events for deliveries, bounces, complaints, domains and contacts. Event list, payloads, svix-* / Standard Webhooks signature verification and retries.
- [SMTP relay](https://docs.pidgely.com/guides/smtp.md): Send through smtp.pidgely.com on ports 587 or 465 with user pidgely and your API key as password. Examples for Nodemailer, Django, Rails, Laravel and Spring.
- [Suppressions](https://docs.pidgely.com/guides/suppressions.md): Hard bounces, spam complaints and unsubscribes are suppressed automatically, account-wide. How suppression affects sends and how to manage the list.
- [Deliverability best practices](https://docs.pidgely.com/guides/deliverability.md): What Pidgely does for your inbox placement, and the practices on your side that matter most - authentication, list hygiene, separate streams, complaints and warm-up.
- [Migrate from Resend](https://docs.pidgely.com/guides/migrate-from-resend.md): Move from Resend to Pidgely - switch to the Pidgely SDK (same method names), move domains, webhooks, contacts and suppressions, and the differences to know.

## SDKs & tools

- [SDKs](https://docs.pidgely.com/sdks.md): Official Pidgely SDKs for Go (published), Node.js, Python, PHP and Ruby (preview) - install, configure and send your first email.
- [MCP server](https://docs.pidgely.com/mcp.md): Let AI assistants and agents send email and manage Pidgely through the Model Context Protocol. Configuration for Claude Desktop, Claude Code and Cursor (preview).

## Platform

- [Architecture](https://docs.pidgely.com/platform/architecture.md): How Pidgely accepts, paces, signs, routes and tracks email - one Go binary in stateless roles over PostgreSQL, with its own MTA and feedback loop.
- [Scaling](https://docs.pidgely.com/platform/scaling.md): How Pidgely grows from one node to independent fleets by configuration, not rewrites - roles, per-kind workers, read replicas, partitions and an external broker.

## API reference

- [API reference](https://docs.pidgely.com/api-reference.md): Every Pidgely endpoint, generated from the OpenAPI 3.1 document, with parameters, request examples in six languages, responses and errors.

### Emails

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

### Domains

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

### API keys

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

### Webhooks

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

### Templates

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

### Contacts

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

### Segments

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

### Broadcasts

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

### Suppressions

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

### Audiences (legacy)

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

### Native API (v1)

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

## Resources

- [Changelog](https://docs.pidgely.com/changelog.md): Notable changes to the Pidgely API, SMTP relay and documentation.
- [Support](https://docs.pidgely.com/support.md): How to get help with Pidgely - email support, what to include in a request, and where to check service status.
- [Security](https://docs.pidgely.com/security.md): How to report a vulnerability to Pidgely, and how the platform protects API keys, secrets, webhooks and your sending reputation.

## Optional

- [OpenAPI 3.1 (YAML)](https://docs.pidgely.com/openapi.yaml): machine-readable API description
- [Blog](https://pidgely.com/blog/): deliverability articles (SPF/DKIM/DMARC, bounces, warm-up)