Email API developer documentation

SDKs and REST

Choose an integration

Registry installation appears here after the beta artifact passes clean-consumer verification.

import { PulsePigeon } from "@blitzglobaltech/pulsepigeon";

const client = new PulsePigeon(process.env.PULSEPIGEON_API_KEY!);

await client.messages.send({
  project_id: "proj_123",
  from_email: "[email protected]",
  to: [{ email: "[email protected]" }],
  subject: "Welcome",
  text: "Hello from PulsePigeon."
}, { idempotencyKey: "welcome-user-123" });

Idempotency support

POST /v1/messages accepts an optional Idempotency-Key header. When you supply one, retrying the same key with the same body returns the original accepted result instead of sending again — strongly recommended for any retry loop or distributed send path.

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; supply an Idempotency-Key header per business event for safe retries.
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"
  }'

Personalized transactional batches

POST /v1/messages/batch accepts 1 to 100 items and at most 10 MB of decoded JSON. Every item requires a unique idempotency_key and can contain an inline message or a published template with its own recipient and variables. The response uses partial atomicity: accepted items include their message IDs, while rejected items include an HTTP-style status and error code. Retry the same items with the same keys to replay accepted results without duplicate sends and retry previously failed work.

curl -X POST "$PULSEPIGEON_API_URL/v1/messages/batch" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $PULSEPIGEON_API_KEY" \
  -d '{
    "items":[{
      "idempotency_key":"invoice-123-user-456",
      "message":{
        "project_id":"proj_123",
        "from_email":"[email protected]",
        "to":[{"email":"[email protected]"}],
        "subject":"Your invoice",
        "text":"Invoice 123 is ready."
      }
    }]
  }'

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.csv

Error 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	Review your workspace sending status and contact support if sending remains paused.
429	Rate limited	Back off until tenant or provider capacity resets.