Sending Transactional Email with Postscale

Before you send

Complete these prerequisites:

1. Verify the sending domain.
2. Confirm DKIM and DMARC pass.
3. Create an API key with sending scope.
4. Choose a From address users recognize.
5. Set up delivery webhooks for bounces and complaints.

The domain setup guide covers DNS.

Send a simple message

Use the REST API for application-triggered mail:

curl https://api.postscale.io/v1/emails \
  -H "Authorization: Bearer $POSTSCALE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <hello@mail.example.com>",
    "to": [{"email": "user@example.net"}],
    "subject": "Your receipt",
    "html": "<p>Thanks for your purchase.</p>",
    "text": "Thanks for your purchase."
  }'

Always provide a plain-text part for clients that block HTML.

Use idempotency for retried actions

Payment callbacks, signup flows, and queue workers can retry. Use a stable idempotency key so the same application action does not produce duplicate mail.

Good keys include:

1. receipt:{payment_id}
2. password-reset:{request_id}
3. invoice:{invoice_id}:sent

Avoid using a random key generated on each retry.

Attach metadata

Metadata lets you correlate later delivery events:

{
  "metadata": {
    "tenant_id": "org_123",
    "template": "receipt",
    "order_id": "ord_456"
  }
}

Keep metadata small and avoid secrets. It may appear in logs or webhook payloads.

Subscribe to delivery webhooks

Submission means Postscale accepted the email. It does not mean the final mailbox accepted it. Delivery webhooks close that loop.

At minimum, handle:

1. Delivered.
2. Deferred.
3. Bounced.
4. Complained.
5. Suppressed.

Use these events to update user-facing status, suppress bad recipients, and alert on unusual failure rates.