Duplicate Emails

​

Which Kind of Duplicate Is It?

​

Duplicate API Sends

​

Why a Retry Sends Twice

​

Fix It with an Idempotency-Key

curl -X POST https://app.lettr.com/api/emails \
  -H "Authorization: Bearer lttr_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-confirmation-10482" \
  -d '{
    "from": "orders@example.com",
    "to": ["customer@example.net"],
    "subject": "Order #10482 confirmed",
    "template_slug": "order-confirmation",
    "substitution_data": { "order_id": "10482" }
  }'

• First request: the email is queued and the response carries data.request_id.
• Replay with the same key and payload: the response carries the same data.request_id plus an Idempotency-Replayed: true header. No second email goes out.
• Same key, different payload: 409 with error_code idempotency_key_conflict. Lettr refuses it rather than sending a second, different email.
• Same key while the first request is still being processed: 409 with error_code idempotency_in_progress and a Retry-After: 1 header.

​

Handle idempotency_in_progress

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': idempotencyKey,
  },
  body,
});

const data = await response.json().catch(() => ({}));

if (response.status === 409 && data.error_code === 'idempotency_in_progress') {
  const seconds = Number(response.headers.get('Retry-After')) || 1;
  await new Promise((resolve) => setTimeout(resolve, seconds * 1000));
  // Send the same request again with the same key and the same body.
}

​

Choose a Key That Survives Retries

​

Keep the Payload Identical

• the payload is rebuilt from a record that changed between attempts, for example an order object whose total was updated
• the template was edited between the first attempt and the retry, so the resolved content differs
• a timestamp or a random value is part of substitution_data

​

Know the Limits

• 24 hours. A retry after the window is a new request and sends a new email. Idempotency is not an unlimited exactly-once guarantee.
• Scoped to your API key. The same key sent with a different API key is treated as a different key.
• Only POST /emails. Scheduled sends (POST /emails/scheduled) ignore the header. Lettr already protects its own dispatch of a scheduled email, so a worker that dies mid-send does not deliver it twice, but a duplicate request that creates a second scheduled email is still your responsibility.
• Quota and rate limits still apply. A retry after you used up your quota gets a 429, not a replay.
• Metadata does not deduplicate. Putting an idempotency_key field inside metadata stores it on the message and echoes it in webhooks. Only the header enables deduplication.
• SMTP has no header. The Idempotency-Key header is part of the HTTP API, and Lettr’s SMTP service has no equivalent. Deduplicate SMTP sends in your own application before submitting the message.

​

Duplicate Campaigns

• Same key, same payload: the original campaign comes back with 201 and an Idempotency-Replayed: true header, not a second draft.
• Same key, different payload: 409 idempotency_key_conflict.
• Same key while the first request is still running: 409 idempotency_in_progress with Retry-After: 1.
• Retention: the key is remembered for 24 hours.
• Scope: campaign keys are scoped to your team.

​

Duplicate Webhook Events

​

Why the Same Event Arrives Twice

• The server processed the event and returned 200, but the response never reached Lettr.
• The handler did slow work before responding and crossed the 30 second limit.

​

Deduplicate on event_id

[
  {
    "msys": {
      "message_event": {
        "type": "delivery",
        "event_id": "92356927693813856",
        "transmission_id": "84273662514790325",
        "rcpt_to": "customer@example.net",
        "timestamp": "1460989507"
      }
    }
  }
]

app.post('/webhooks/lettr', async (req, res) => {
  // Acknowledge first so the delivery does not time out.
  res.sendStatus(200);

  for (const item of req.body) {
    const event = Object.values(item.msys ?? {})[0];
    if (!event?.event_id) continue;

    try {
      // Unique constraint on event_id
      await db.processedWebhooks.insert({ event_id: event.event_id });
    } catch (err) {
      if (err.code === '23505') continue; // PostgreSQL unique violation: already handled
      throw err;
    }

    await handleEvent(event);
  }
});

​

Make the Effect Idempotent as Well

​

Check the Recipient Side

• Forwarding rules. The recipient’s mailbox forwards to a second address that is also read in the same mail client.
• Mailing lists and aliases. One alias that expands to several mailboxes delivered to the same person.
• The same address twice. The address appears in both to and cc, or a list of recipients you built contains it twice with different capitalization. Deduplicate your recipient list before sending.
• Client sync issues. Some mail clients show a message twice after a failed sync.

​

Prevention Checklist

​

Related Topics