Authentication and scopes
Authorization: Bearer pp_live_...
Authentication: Project or workspace API key
Choose only the scopes you need. Workspace keys are owner-created and can enforce environment, IP, sender-domain, and expiry restrictions.
Public API v1
API reference
Search the customer API by resource, scope, or behavior.
15 reference sections
Messages, scheduling, and attachments
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.
Message status and events
GET /v1/messages, /v1/message-logs, /v1/events
Authentication: reports:read
Project keys see only their project. Results follow the workspace retention policy.
Domains and DMARC
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.
Templates
/v1/templates
Authentication: Signed workspace session
Create immutable versions, publish a version, preview output, and use published templates in batch sends.
Contacts and subscriber lists
/v1/subscriber-lists
Authentication: contacts:*
Project keys create and read lists only in their project. Opt-in requests also require messages:send.
Segments
/v1/segments
Authentication: Signed workspace session
Build reusable audience rules from contact profile and event data.
Campaigns
/v1/campaigns
Authentication: Signed workspace session
Create, schedule, pause, resume, cancel, preview, and inspect campaigns.
Workflows
/v1/automations
Authentication: Signed workspace session
Version, publish, trigger, inspect, and retry workflow runs.
Inbound mail
/v1/inbound
Authentication: Signed workspace session
Configure inbound routes and inspect retained inbound messages.
Suppressions and deletion
/v1/compliance/suppressions, /v1/suppressions/*
Authentication: Workspace key with suppressions:*
Suppression and deletion act across the workspace and require privileged key issuance.
Status webhooks
/v1/webhooks/status
Authentication: Workspace key with webhooks:*
Verify every delivery with the SDK helper. Delivery history exposes retries and final outcomes.
Rate limits and errors
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.
Pagination and retention
limit, since, until
Authentication: Route-specific read scope
List endpoints use bounded limits. Message reads cannot exceed the active retention window.
Idempotency
Idempotency-Key
Authentication: Mutation-specific scope
Reusing a key with the same body returns the original accepted result. A changed body returns 409.
Webhook verification and retries
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.
The helpers reject malformed headers, invalid signatures, and timestamps outside the default five-minute tolerance. Keep the current and previous secret during rotation, 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.
Contract and support
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.