Idempotency

Retrying a create without creating twice.

Creation endpoints accept a client_id — your own identifier for the thing you are creating.

curl -X POST https://api.carlyemail.com/v0/inboxes \
  -H "Authorization: Bearer $CARLYEMAIL_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"username": "pepsi", "client_id": "onboarding-run-4821"}'

Send the same client_id again and you get the original resource back rather than a second one. This matters more for agents than for ordinary clients: a model that retries a tool call after a timeout should not end up with two mailboxes.

Sign-up is the deliberate exception. An owner email identifies an account but does not authenticate its owner, so repeating sign-up returns account_exists without rotating any keys. A person who lost a key signs in with an emailed code through the console.