Idempotency

Use idempotency keys to safely retry requests without duplicate sends.

What is Idempotency?

Idempotency ensures that retrying a request produces the same result as the original request. This prevents duplicate emails if a request times out or fails after the email was already sent.

Using Idempotency Keys

Add the Idempotency-Key header to your request:

curl -X POST https://getmailer.co/api/emails \
  -H "Authorization: Bearer gm_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-confirmation-12345" \
  -d '{
    "from": "orders@yourdomain.com",
    "to": "customer@example.com",
    "subject": "Order #12345 Confirmed",
    "html": "<p>Your order has been confirmed!</p>"
  }'

How It Works

First request with a key processes normally and caches the response
Subsequent requests with the same key return the cached response
Keys are unique per API key (different accounts can use the same key)
Keys expire after 24 hours

Key Requirements

Maximum length: 255 characters
Allowed characters: alphanumeric, hyphens, underscores
Keys are case-sensitive
Generate unique keys (UUIDs work well)

Best Practices

Good: Unique per logical operation

order-confirmation-{orderId}
password-reset-{userId}-{timestamp}
welcome-{userId}

Bad: Reusing keys

send-email (too generic)
1 (will collide)
test (not unique)

Response Behavior

Scenario	Response
First request	Normal response, cached for 24h
Retry with same key + body	Cached response returned
Same key, different body	`409 Conflict`
Key expired (24h+)	Processes as new request

Implementation Example

import { v4 as uuidv4 } from 'uuid';

async function sendOrderConfirmation(order) {
  // Use order ID for idempotency - safe to retry
  const idempotencyKey = `order-confirmation-${order.id}`;

  const response = await fetch('https://getmailer.co/api/emails', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer ' + apiKey,
      'Content-Type': 'application/json',
      'Idempotency-Key': idempotencyKey
    },
    body: JSON.stringify({
      from: 'orders@yourdomain.com',
      to: order.customerEmail,
      subject: `Order #${order.id} Confirmed`,
      html: renderOrderEmail(order)
    })
  });

  return response.json();
}