docs(emails): add optional idempotency_key to POST /api/emails - #285
docs(emails): add optional idempotency_key to POST /api/emails#285sweetmantech wants to merge 1 commit into
Conversation
|
Bugbot is not enabled for your account, so this pull request was not reviewed. Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs. |
|
Warning Review limit reached
Next review available in: 46 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (1)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
1 issue found across 1 file
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="api-reference/openapi/accounts.json">
<violation number="1" location="api-reference/openapi/accounts.json:3590">
P2: Add `minLength: 1` to `idempotency_key` so an empty string is rejected at the schema level rather than silently bypassing deduplication or requiring backend special-casing.</violation>
</file>
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
| "idempotency_key": { | ||
| "type": "string", | ||
| "maxLength": 256, | ||
| "description": "Optional key that makes this send exactly-once. Two requests carrying the same key deliver a single email; the duplicate returns the original send's id instead of delivering again. Intended for retried or replayed callers — scheduled task runs re-execute on crash or redeploy, and without a key each re-execution delivers another copy of the same report. Use a value that is stable across retries of the same logical send and unique between different sends.", | ||
| "example": "chat_9f2c1e04-6b7a-4c3d-9a1e-2f5b8c7d0e11:msg_IVjxAcIRghYu" | ||
| }, |
There was a problem hiding this comment.
P2: Add minLength: 1 to idempotency_key so an empty string is rejected at the schema level rather than silently bypassing deduplication or requiring backend special-casing.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At api-reference/openapi/accounts.json, line 3590:
<comment>Add `minLength: 1` to `idempotency_key` so an empty string is rejected at the schema level rather than silently bypassing deduplication or requiring backend special-casing.</comment>
<file context>
@@ -3587,6 +3587,12 @@
"type": "string",
"description": "Chat ID to include a chat link in the email footer. Use [Create Chat](/api-reference/chat/create) to create one."
},
+ "idempotency_key": {
+ "type": "string",
+ "maxLength": 256,
</file context>
| "idempotency_key": { | |
| "type": "string", | |
| "maxLength": 256, | |
| "description": "Optional key that makes this send exactly-once. Two requests carrying the same key deliver a single email; the duplicate returns the original send's id instead of delivering again. Intended for retried or replayed callers — scheduled task runs re-execute on crash or redeploy, and without a key each re-execution delivers another copy of the same report. Use a value that is stable across retries of the same logical send and unique between different sends.", | |
| "example": "chat_9f2c1e04-6b7a-4c3d-9a1e-2f5b8c7d0e11:msg_IVjxAcIRghYu" | |
| }, | |
| "idempotency_key": { | |
| "type": "string", | |
| "minLength": 1, | |
| "maxLength": 256, | |
| "description": "Optional key that makes this send exactly-once. Two requests carrying the same key deliver a single email; the duplicate returns the original send's id instead of delivering again. Intended for retried or replayed callers — scheduled task runs re-execute on crash or redeploy, and without a key each re-execution delivers another copy of the same report. Use a value that is stable across retries of the same logical send and unique between different sends.", | |
| "example": "chat_9f2c1e04-6b7a-4c3d-9a1e-2f5b8c7d0e11:msg_IVjxAcIRghYu" | |
| }, |
1 participant
Contract for the idempotent-send row of chat#1918. Docs lead; the api PR follows.
Why
runAgentWorkflowruns 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) toSendEmailRequest. 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, sinceassistantMessageIdis 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.jsondoes not round-trip byte-identically throughjson.load/json.dumps(verified), so this is an anchored text edit at the property boundary. Re-validated: parses, andidempotency_keyis present onSendEmailRequest.properties.🤖 Generated with Claude Code
Summary by cubic
Added an optional
idempotency_keyto POST/api/emailsto make email sends exactly-once on retries or redeploys; duplicates return the original send ID. Additive and non-breaking. Addresseschat#1918.idempotency_keyis a string up to 256 characters; example included in the schema.Written for commit 09ac868. Summary will update on new commits.