docs(emails): add optional idempotency_key to POST /api/emails

SW
3mo ago
+6-0

Contract for the idempotent-send row of chat#1918. Docs lead; the api PR follows.

Why

runAgentWorkflow runs the whole agent loop — including the email send — inside a single step, so a crash or a redeploy re-executes from the top and delivers the report again.

Reproduced 2026-07-30 on chat 329c4760-646b-4749-a7e7-82fd64f9cf72: email sent 21:21:45, production deployment went live 21:28:47, second email sent 21:40:32. Both passes ran end to end — the second deduped its content against a ledger the first had written. Method Music received the same report 3× on 2026-07-29 and again 3× on 2026-07-30.

What changes

Adds an optional idempotency_key (max 256 chars) to SendEmailRequest. Two requests carrying the same key deliver one email; the duplicate returns the original send's id.

Additive and non-breaking — callers that omit it are unaffected.

Scope

This documents the primitive. Deriving the key automatically per turn (chatId + assistantMessageId) lands with the workflow decomposition, since assistantMessageId is not available at this API boundary today. Landing the parameter first means any caller that already knows its retry identity can be exactly-once immediately, and it is the defence-in-depth layer the issue calls for even after steps exist: a crash after the Resend call but before the send step journals would still re-send without it.

Edit method

accounts.json does not round-trip byte-identically through json.load/json.dumps (verified), so this is an anchored text edit at the property boundary. Re-validated: parses, and idempotency_key is present on SendEmailRequest.properties.

🤖 Generated with Claude Code

Summary by cubic

Added an optional idempotency_key to POST /api/emails to make email sends exactly-once on retries or redeploys; duplicates return the original send ID. Additive and non-breaking. Addresses chat#1918.

  • New Features
    • idempotency_key is a string up to 256 characters; example included in the schema.
    • Use a value that’s stable across retries and unique per logical send.