Custom headers

Idempotency-Key and automatic List-Unsubscribe headers today. Arbitrary custom headers are on the roadmap.

Headers you can set today

Idempotency-Key (request header)

Pass on POST /emails to make sends safely retryable:

Idempotency-Key: otp:user@example.com:482193

Same key within 24 hours returns the original email instead of sending again. See Idempotency keys.

List-Unsubscribe (automatic)

When enable_unsubscribe: true on the JSON body, Piisend adds RFC-compliant unsubscribe headers before delivery:

  • List-Unsubscribe: <https://…/unsubscribe/{token}>
  • List-Unsubscribe-Post: List-Unsubscribe=One-Click

See Unsubscribe link.

Arbitrary custom headers (not supported yet)

You cannot currently pass custom SMTP headers (e.g. X-Entity-Ref-ID, X-Campaign-Id) on POST /emails.

Workarounds:

  • Encode metadata in template_vars and render into the HTML/text body.
  • Track campaign IDs in your database keyed by the returned email id.
  • Use webhooks to correlate delivery events with your internal IDs.

Native custom header support is planned for a future API version.

Related

Documentation

Integrate with the REST API

Quickstart, API reference, and webhooks—everything you need to send from your app.

QuickstartAPI reference