Idempotency

Networks fail. If a request times out you can’t tell whether the email was accepted. Send an Idempotency-Key header and retrying becomes safe:

curl -X POST https://api.vaartix.com/emails \
  -H "Authorization: Bearer $VAARTIX_API_KEY" \
  -H "Idempotency-Key: order-1042-receipt" \
  -H "Content-Type: application/json" \
  -d '{ "from": "[email protected]", "to": "[email protected]", "subject": "Your receipt", "text": "..." }'

Node.js

await vaartix.emails.send(email, { idempotencyKey: `order-${order.id}-receipt` });

How it works

• The same key with the same body within 24 hours returns the first email’s ID. Nothing is sent again.
• The same key with a different body returns 409 idempotency_conflict, because it is almost certainly a bug.
• After 24 hours the key can be used again.
• Keys are per team and up to 256 characters.

Choosing keys

Base the key on what the email is about, not on the request: order-1042-receipt, user-881-welcome, [email protected]. A random key per attempt defeats the purpose.