Idempotency

A request can time out after Postilio accepted it. Sending it again could deliver the email twice. With an Idempotency-Key header you can safely send it again: Postilio recognizes the repeat and answers as it did the first time, without sending anything again.

curl https://api.postilio.eu/v1/emails \
  -H "Authorization: Bearer $POSTILIO_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-receipt" \
  -d '{
    "from": "Acme <orders@mail.example.com>",
    "to": ["ada.lovelace@example.com"],
    "subject": "Your order 1042",
    "text": "Thank you for your order."
  }'

In Node or C#, add the same header to the request: 'Idempotency-Key': 'order-1042-receipt' in the headers of fetch, or request.Headers.Add("Idempotency-Key", "order-1042-receipt") on an HttpRequestMessage.

How it works

• The key is any string of 1 to 256 characters that you choose per email you mean to send once: an order number with the kind of mail, say, or a UUID you store with the job. It is only for POST /v1/emails.
• Within 24 hours of the first request, a request with the same key and the same body answers 202 with the same ids and suppressed as the first one, and sends nothing.
• The same key with another body answers 409 with {"error": "idempotency_key_reused_with_different_request"}. Any difference in the fields counts, the order of to too; the layout of the JSON does not.
• Only an accepted request is remembered. A request that answered 400, 422 or 429 stored nothing, so you can fix it and send it again with the same key.
• Two at once. When the same request arrives twice at the same time, the second waits for the first and gets its answer.
• Per project and per mode: a test key and a live key do not share keys, and neither do two projects.
• A repeat is checked first. The sender's domain, the key's restrictions and the sandbox's recipients are checked before Postilio looks the key up, so a repeat after the domain was removed answers that error (422), not the first answer. Nothing is sent twice either way.
• After 24 hours the key is free again and counts as a new request.

SMTP

Over SMTP, the Message-ID header is the key. A client that sends a message again after a lost reply, with the same Message-ID to the same recipients within 24 hours, gets 250 and the message is not sent twice. The same Message-ID with other content is refused with 554 5.6.0 message_id_reused_with_different_content. A message without a Message-ID is sent every time it arrives.