---
title: "Designing idempotent sends with the PulsePigeon email API"
canonical: https://pulsepigeon.com/blog/idempotent-sends-with-the-email-api
last_updated: 2026-08-04
---

# Designing idempotent sends with the PulsePigeon email API

How to use idempotency keys when sending transactional email so retries after a timeout never result in a duplicate message reaching a customer.

Network timeouts are ambiguous: a client that never receives a response cannot tell whether the send failed before or after the message was accepted. Retrying blindly risks a duplicate email reaching the recipient. Use the [HTTP API error reference](/docs/errors) when classifying a failed request.

The PulsePigeon send endpoint accepts an idempotency key on every request, passed as the `Idempotency-Key` header. Replaying the same request with the same key returns the original result instead of enqueueing a second send, so a retried request after a timeout is always safe. See the [developer documentation](/docs/developer) for the full request reference.

Generate idempotency keys per logical send, not per HTTP attempt. A good source is the identifier of the event that triggered the send, such as an order ID or a password-reset request ID, so retries from any layer of your stack collapse to the same key.

Idempotency keys are scoped and expire after a fixed retention window. Do not reuse a key for a genuinely new message once that window has passed, or the new send will be rejected as a duplicate of the old one.

Combine idempotency keys with signed delivery-event webhooks to close the loop: once a send is accepted, your system can confirm delivery, bounce, or complaint status without polling the API.