Sending
Retries and idempotency
Retry safely without sending an email twice.
NeedsAny accountTest keys work as soon as you sign up. Nothing is delivered.
Networks fail. If a request times out you can't tell whether the email was accepted, so you retry, and without protection the customer gets two receipts. An Idempotency-Key fixes that.
Idempotency keys
Send a unique Idempotency-Key header (up to 255 characters) with any POST. For 24 hours:
- the same key with the same body returns the first response, with the header
Idempotent-Replayed: true, and doesn't send again; - the same key with a different body returns
409 idempotency_conflict.
Use a key that means something in your system, such as the order or event it's for:
await pm.emails.send(receipt, { idempotencyKey: `receipt-${order.id}` });What to retry
| Response | Retry? |
|---|---|
| Network error or timeout | Yes, with the same idempotency key |
429 rate_limited | Yes, after Retry-After seconds |
500, 503 | Yes, with backoff (for example 0.5 s, 1 s, 2 s) |
429 quota codes with quota_behavior: "reject" | No: the limit won't lift in seconds |
Other 4xx | No: fix the request first |
The Node SDK does this for you
The SDK retries network errors, 429 and 5xx twice by default, waits as long as Retry-After says (up to 60 seconds), and adds an idempotency key to every POST so its own retries are safe. Change it per client or per call:
const pm = new PadiMail(process.env.PADIMAIL_API_KEY, { maxRetries: 4, timeout: 10_000 });
await pm.emails.send(email, { maxRetries: 0 });Was this page helpful?