Developer documentation
API integration guide
Server-side examples for integrating transactional and lifecycle email.
Integration path
| Step | Rule |
|---|---|
| Create project | POST /v1/projects with an Idempotency-Key for the setup operation. |
| Create API key | POST /v1/api-keys and store the one-time secret immediately. |
| Send message | POST /v1/messages with one idempotency key per business event. |
| Track status | Use message logs or signed status webhooks for final delivery state. |
Send example
curl -X POST "$PULSEPIGEON_API_URL/v1/messages" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: password-reset-user-123-event-456" \
-H "Authorization: Bearer $PULSEPIGEON_API_KEY" \
-d '{
"project_id":"proj_123",
"from_email":"[email protected]",
"to":[{"email":"[email protected]"}],
"subject":"Reset your password",
"text":"Use the secure reset link in this email.",
"category":"security"
}'Webhook signature
Verify HMAC-SHA256 over timestamp plus canonical JSON body.
PulsePigeon-Signature: t=1783380000,v1=<hex-hmac>
signed_payload = "<timestamp>.<canonical-json-body>"Suppression import
curl -X POST "$PULSEPIGEON_API_URL/v1/suppressions/import" \
-H "Content-Type: text/csv" \
-H "Authorization: Bearer $PULSEPIGEON_API_KEY" \
--data-binary @suppressions.csvError handling
| Status | Meaning | Action |
|---|---|---|
| 202 | Accepted | Track final state through logs or webhooks. |
| 409 | Idempotency conflict | Use the same body or generate a new key. |
| 423 | Sending halted | Stop sends and review suspension or kill-switch state. |
| 429 | Rate limited | Back off until tenant or provider capacity resets. |