Public API v1
Search the customer API by resource, scope, or behavior.
16 reference sections
Authorization: Bearer pp_live_... or pp_test_...
Authentication: Project or workspace API key
Test projects get pp_test_ keys; production projects and workspace keys get pp_live_ keys. The project record controls the environment. Choose only the scopes you need.
POST /v1/messages, POST /v1/messages/batch
Authentication: messages:send
Use an Idempotency-Key for retry-safe sends. Scheduling and attachment fields are part of the message request.
GET /v1/messages, /v1/message-logs, /v1/events
Authentication: reports:read
Project keys see only their project. Results follow the workspace retention policy.
GET /v1/bounces, GET /v1/bounces/{id}, POST /v1/bounces/{id}/activate
Authentication: reports:read for reads; privileged session or all-environment workspace key with suppressions:* for reactivation
Filter by type, email, date, or message ID. Reactivation removes only a matching bounce-caused suppression and returns 409 otherwise.
GET /v1/domains, POST /v1/domains/{id}/check
Authentication: Workspace key with reports:read or domains:*
Domain state is workspace-wide. DNS checks are rate limited.
/v1/templates
Authentication: Signed workspace session
Create immutable versions, publish a version, preview output, and use published templates in batch sends.
/v1/subscriber-lists
Authentication: contacts:*
Project keys create and read lists only in their project. Opt-in requests also require messages:send.
/v1/segments
Authentication: Signed workspace session
Build reusable audience rules from contact profile and event data.
/v1/campaigns
Authentication: Signed workspace session
Create, schedule, pause, resume, cancel, preview, and inspect campaigns.
/v1/automations
Authentication: Signed workspace session
Version, publish, trigger, inspect, and retry workflow runs.
/v1/inbound
Authentication: Signed workspace session
Configure inbound routes and inspect retained inbound messages.
/v1/compliance/suppressions, /v1/suppressions/*
Authentication: Workspace key with suppressions:*
Suppression and deletion act across the workspace and require privileged key issuance.
/v1/webhooks/status
Authentication: Workspace key with webhooks:*
Verify every delivery with the SDK helper. Delivery history exposes retries and final outcomes.
401, 403, 409, 422, 423, 429, 5xx
Authentication: All public operations
Typed SDK errors preserve the stable API code. Honor Retry-After on 429 responses.
limit, since, until
Authentication: Route-specific read scope
List endpoints use bounded limits. Message reads cannot exceed the active retention window.
Idempotency-Key
Authentication: Mutation-specific scope
Reusing a key with the same body returns the original accepted result. A changed body returns 409.
PulsePigeon-Signature contains a Unix timestamp and an HMAC-SHA256 digest over canonical JSON. Verify it with the TypeScript or Python SDK helper before parsing business fields.
A default five-minute tolerance would reject delayed deliveries; the helpers instead default to 3600 seconds. Set a longer tolerance when configured retries or queue delays require it. They do not enforce the exact header grammar, so validate syntax separately if your receiver requires it. Rotation changes the signing secret immediately; accept both old and new secrets while old deliveries finish, and expect new deliveries to retry until the new secret reaches your receiver. Reject repeated event IDs in your replay window and return a successful 2xx response only after durable processing.
Delivery history reports attempts, the next retry time, final response status, and dead-letter state. Event payload schemas are part of the downloadable OpenAPI contract.
Subscribe to subscription.changed for preference, one-click unsubscribe, suppression, bounce, and complaint changes. Its payload includes the recipient, category, source, and old and new state. Subscribe to smtp.submission_error for tenant-scoped authenticated SMTP failures. It includes the project, credential ID, error code, and assigned message ID when available.
The public OpenAPI file excludes operator, provider-ingestion, billing-provisioning, and runtime-secret operations.
Version 1 accepts backward-compatible additions. Breaking changes require a new API version. Deprecations appear in the changelog and documentation with a default 180-day window unless security or legal risk requires faster removal.
SDK quickstarts · Error catalog · Webhook verification · API policies · Changelog