Idempotency

A key you can derive againcurl -X POST https://api.transmit.dev/v1/emails \
  -H "Authorization: Bearer $TRANSMIT_API_KEY" \
  -H "Idempotency-Key: order-1042-shipped" \
  -H "Content-Type: application/json" \
  -d '{"from":"hello@yourdomain.com","to":"you@example.com","subject":"Shipped","text":"On its way."}'

Where it is required

POST /v1/emails and POST /v1/sms require an Idempotency-Key header of at most 255 characters. Without one you get 400 before anything is charged.

What a repeat does

We store the key against your organization along with a hash of the request. Send the same key again with the same request and you get the original receipt — same message id, no second send, no second charge. Send the same key with a different request and you get 409, because one of the two is a mistake and we would rather not guess which.

Choosing a key

• Derive it from the thing that caused the send. order-1042-shipped is a good key: if your worker retries, it computes the same key and cannot double-send.
• A random UUID is fine when the send is genuinely one-off — but generate it before the first attempt, not inside the retry, or every attempt is a new message.
• Do not reuse a key across different messages. That is the 409.