API Idempotency for Email Account Creation: Prevent Duplicate Tasks and Charges

Account creation requests need protection from network ambiguity

A client can time out after the server accepts a task but before the response reaches the client. Without an idempotency strategy, an automatic retry may create a second valid task for the same internal order. The duplicate can consume budget and produce sensitive output nobody intended to own.

Idempotency lets repeated delivery of one logical request resolve to the same creation decision. It does not make every error retryable, and it does not replace task status, limits, or final reconciliation.

Generate and persist the key before sending the request

Create a high-entropy key for the internal job and store it durably with provider, quantity, requester, approval reference, and expected credit estimate before the first API call. If the process restarts, it must recover the same key rather than inventing another one.

Keep key generation at the boundary that understands the logical job. A low-level HTTP retry library should reuse a supplied key; it should not decide that two separate business requests are the same.

• Internal job ID
• Idempotency key
• Canonical provider and quantity
• Approval and budget reference
• MailMaker task ID when known
• Current recovery state

Bind the key to a canonical request payload

A repeated key should represent the same provider, quantity, environment, and other creation parameters. Store or derive a canonical payload fingerprint so a later request cannot silently reuse the key with different work.

When the same key arrives with a different payload, return or surface a conflict that requires investigation. Do not update the original task and do not create a second task under ambiguous ownership.

Combine idempotency with bounded retries and status polling

Retry transport uncertainty with backoff, jitter, and the same key. Once a MailMaker task ID is known, transition from creation recovery to task retrieval. Poll on a bounded schedule and stop on completed, partial, or failed.

Validation failures, insufficient balance, unsupported requests, and permanent errors should not enter a blind retry loop. Store an error class and route the job to the owner able to correct or reject it.

• Same key for uncertain creation
• Backoff and maximum attempts
• Persist returned task ID
• Bound polling by interval and deadline
• Manual review for unresolved ambiguity

Prove duplicate prevention with reconciliation and safe observability

Record idempotent replays, conflicts, recovered task IDs, duplicate attempts prevented, and jobs moved to manual review. Do not log raw API keys or account credentials. Correlation identifiers and task metadata are sufficient for most diagnosis.

At terminal state, compare the internal job with the authoritative task: provider, requested count, successful count, failed count, and credits. A job closes only when one logical request, its task, its accepted output, and its final charge can be followed in one record.