Idempotency

A retried send can deliver the same email twice. A network timeout hides whether the first attempt reached Lettr, and queue consumers and serverless platforms invoke the same handler more than once. The Idempotency-Key header is the fix: reusing the same key, payload, and API key within 24 hours returns the original transmission result without sending another email.

The contract

Send an optional Idempotency-Key header with POST /api/emails. Reusing the same key, payload, and API key within 24 hours returns the original transmission result without sending another email. Replayed responses include Idempotency-Replayed: true and the same data.request_id. Requests without this header are processed independently. The rules that follow from it:

Key format. Keys are 1 to 255 characters using letters, numbers, ., _, and -.
One key per intended email. A new intended email requires a new key. Reusing a key with a different payload returns 409 idempotency_key_conflict rather than a second send.
Replays are free. A replayed response doesn’t send the email again and doesn’t count against your quota again.
Normal checks run first. Authentication, sending-domain and quota checks run before the key is looked up, so a retry after your quota is used up still gets a 429.
Only POST /emails. Scheduled sends (POST /emails/scheduled) ignore the header.
Retention is 24 hours. This is not an unlimited exactly-once guarantee. A retry after the window is a new request and sends a new email.
Metadata does not deduplicate. metadata.idempotency_key is stored and echoed in webhooks like any other metadata field. Only the header enables deduplication.

Choosing a key

Derive the key from the business event the email belongs to, not from the attempt. Generate or derive one key per intended email, then reuse it across every retry and handler invocation. Do not generate a new timestamp, random value, or attempt counter for each retry. A UUID generated once and persisted with the business record works as well as a derived key.

const idempotencyKey = `order-confirmation-${orderId}`;

Include the email’s purpose and the entity it relates to, such as order-confirmation-{order_id} or password-reset-{reset_request_id}. Use a stored identifier rather than a raw token or other user-facing value, which can contain characters outside the allowed key format. A generic key like email-123 lets two different email types collide on the same value.

Sending with a key

The header goes on the request alongside the authorization header. A replayed response carries the Idempotency-Replayed header and the original data.request_id:

const response = await fetch('https://app.lettr.com/api/emails', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.LETTR_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': `order-confirmation-${order.id}`,
  },
  body: JSON.stringify({
    from: 'orders@example.com',
    to: [order.customer_email],
    subject: `Order #${order.id} confirmed`,
    template_slug: 'order-confirmation',
    substitution_data: { order_id: order.id, total: order.total },
    metadata: { order_id: order.id },
  }),
});

const data = await response.json();

if (response.headers.get('Idempotency-Replayed') === 'true') {
  console.log('Replayed earlier send', data.data.request_id);
}

Store data.data.request_id on the order record. The request ID is the handle for delivery status in the API and dashboard, and every webhook event for the message carries it, so a handler can map events back to the order.

Retrying with the same key

A timeout (ETIMEDOUT) or connection reset (ECONNRESET) means the client received no response, but Lettr may already have accepted the email. Retry with the same key and the same payload. If the first attempt got through, the retry returns the original result as a replay; if it did not, the retry sends the email. There is no need to query for the earlier attempt before retrying. Keep the payload byte-for-byte identical across retries and across function invocations. For template sends, the resolved content must not change either, which means both substitution_data and the template itself stay unchanged between attempts. Pass only the fields the template needs rather than a whole mutable record like the order object, so an unrelated update between attempts cannot alter the payload. A changed payload under the same key is a conflict, not a replay.

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

// Retry-After carries seconds or an HTTP date. Without it, back off exponentially with full jitter.
function retryDelay(attempt, retryAfter) {
  if (retryAfter) {
    const seconds = Number(retryAfter);
    const ms = Number.isFinite(seconds) ? seconds * 1000 : Date.parse(retryAfter) - Date.now();
    if (ms > 0) return ms;
  }
  const capMs = Math.min(30_000, 1_000 * 2 ** attempt);
  return Math.random() * capMs;
}

async function sendWithRetry(payload, idempotencyKey, maxAttempts = 3) {
  const body = JSON.stringify(payload);
  let lastError;

  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    let response = null;
    try {
      response = await fetch('https://app.lettr.com/api/emails', {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${process.env.LETTR_API_KEY}`,
          'Content-Type': 'application/json',
          'Idempotency-Key': idempotencyKey,
        },
        body,
        signal: AbortSignal.timeout(30_000),
      });
    } catch (error) {
      // Network failure or timeout. The same key makes the retry safe either way.
      lastError = error;
    }

    let retryAfter = null;
    if (response) {
      // Gateway errors can carry a non-JSON body. Decide from the status either way.
      const data = (await response.json().catch(() => null)) ?? {};

      if (response.ok && data.data?.request_id) {
        return data;
      }

      if (response.ok) {
        // A 2xx with a truncated or malformed body. The same key replays the original result.
        lastError = new Error('Success response could not be parsed');
      } else {
        const retryable =
          response.status >= 500 ||
          response.status === 429 ||
          data.error_code === 'idempotency_in_progress';

        if (!retryable) {
          throw new Error(`${data.error_code}: ${data.message}`);
        }

        lastError = new Error(`${response.status} ${data.error_code}: ${data.message}`);
        retryAfter = response.headers.get('Retry-After');
      }
    }

    if (attempt < maxAttempts) {
      await sleep(retryDelay(attempt, retryAfter));
    }
  }

  throw lastError;
}

A local sent flag on the business record still saves an API call when the outcome is already known, but it is an optimization. The header is what prevents the duplicate.

Error responses

Two 409 responses are specific to idempotent requests. The rest of the retry rules are unchanged and covered in Errors & Retries.

Response	Meaning and action
`409` `idempotency_in_progress`	The original request is still being processed. Retry the same request after `Retry-After` (1 second).
`409` `idempotency_key_conflict`	The key was reused with a different payload. Use a new key for a new email, or send the original payload.
`422` `validation_error`	Correct the invalid key or payload.
`429`	Rate limits and quotas still apply, including to retries.

Using an SDK

Every official SDK takes the key as an argument, so you do not have to set the header yourself. The response carries a replay flag alongside the usual fields.

const result = await lettr.emails.send(
  { from, to, subject, html },
  { idempotencyKey: `order-confirmation-${order.id}` },
);

result.replayed; // true → replayed an earlier send, no second email went out

$response = $lettr->emails()->send($data, new IdempotencyKey("order-confirmation-{$order->id}"));

$response->replayed; // true → replayed an earlier send

response = lettr.emails.send(
    from_email="orders@example.com",
    to=[order.customer_email],
    subject=f"Order #{order.id} confirmed",
    template_slug="order-confirmation",
    idempotency_key=f"order-confirmation-{order.id}",
)

response.replayed  # True → replayed an earlier send

resp, err := client.Emails.Send(ctx, params,
    lettr.WithIdempotencyKey(fmt.Sprintf("order-confirmation-%d", order.ID)))

resp.Data.Replayed // true → replayed an earlier send

let options = CreateEmailOptions::new(from, to, subject)
    .with_idempotency_key(format!("order-confirmation-{}", order.id));

let response = client.emails.send(options).await?;
response.replayed; // true → replayed an earlier send

CreateEmailResponse response = lettr.emails().send(request, "order-confirmation-" + order.getId());

response.isReplayed(); // true → replayed an earlier send

A replay is a success, not an error — the original transmission is returned verbatim. Log it differently if you want the visibility, but do not treat it as a failure.

Laravel is the exception: it does this for you. lettr-laravel derives a key for every queued mail automatically, from the queue job’s UUID plus the payload, so a job retry cannot deliver twice. Pass your own key with Mail::lettr()->idempotencyKey(...) to override it, or set LETTR_IDEMPOTENCY_ENABLED=false to turn the automatic behaviour off. Synchronous sends have no job UUID and so get no automatic key.

Documentation

Quickstart

Learn

Integrations

Resources

The contract

Choosing a key

Sending with a key

Retrying with the same key

Error responses

Using an SDK

​The contract

​Choosing a key

​Sending with a key

​Retrying with the same key

​Error responses

​Using an SDK

The contract

Choosing a key

Sending with a key

Retrying with the same key

Error responses

Using an SDK