What is an idempotency key for direct mail APIs?
An idempotency key for a direct mail API is a stable value attached to one create-mail request. When a client retries the same request, the workflow can recognize the key and return the original state instead of creating another mail record.
HTTP semantics define idempotent methods as requests where multiple identical requests have the same intended effect as one request. Many direct-mail workflows use create requests that need their own retry-safety record. The idempotency key is that record's handle.
Why does idempotency matter for physical mail?
Idempotency matters because a software retry can create physical output. Without a stable retry key, one timeout, network error, or webhook retry can turn a single source event into repeated mail records that later need cleanup.
Digital systems can often delete, void, or hide a mistaken record. Direct mail moves toward proofing, batching, print, postal tracking fields, and later measurement. That makes retry safety an operational control, not just a developer convenience.
Operator rule: the workflow should be able to answer, "Did this retry create new mail, or did it return the original request state?"
When should the idempotency key be created?
Create the idempotency key before the create-mail request is sent. It should be derived from the source event or generated once by the calling system, then reused for retries of the same intended mail request.
Do not generate a fresh key for every retry. A fresh key tells the workflow the request might be new. A stable key lets the workflow return the prior accepted, held, rejected, or released state when the underlying request has already been handled.
What should the idempotency record store?
The idempotency record should store enough context to explain the original request, compare safe retries, and show whether the mail record was accepted, held, rejected, batched, or released.
| Record field | Why it matters | Example |
|---|---|---|
| Idempotency key | Identifies one intended create-mail request. | Source event ID plus campaign or request ID. |
| Payload fingerprint | Helps detect a retry that changed important fields. | Stable hash of recipient, address, template, and campaign fields. |
| Source event | Shows why the request exists. | Cart event, lead event, customer milestone, or manual import row. |
| Recipient key | Connects retry safety to deduplication and suppression review. | Recipient ID, household key, address key, or source-system ID. |
| Campaign ID | Connects the request to the broader mailing effort. | Campaign ID, segment, creative version, and measurement window. |
| Request state | Shows what the first request returned. | Accepted, held, rejected, queued, batched, released, or failed before acceptance. |
| Audit timestamps | Preserves the retry history. | First seen, last retry, state change, reviewer, and notes. |
How should retries behave?
A retry with the same idempotency key should return the original request state when the workflow has already accepted or decided the request. It should not silently create another postcard because the client did not receive the first response.
| Prior state | Safe retry behavior | Record to keep |
|---|---|---|
| Accepted | Return the accepted mail record instead of creating a second one. | Mail record ID, campaign ID, proof state, and acceptance time. |
| Held | Return the held state and reason. | Exception reason, reviewer, and next action. |
| Rejected | Return the rejection state and reason. | Suppression result, invalid input reason, or policy reason. |
| Batched or released | Return the existing batch or release context. | Batch ID, release timestamp, and tracking join fields when available. |
| Failed before acceptance | Allow a new processing attempt under the same key when no mail record exists. | Error state, retry count, and resolution timestamp. |
| Same key, changed payload | Hold or reject for review instead of guessing which request is correct. | Original fingerprint, new fingerprint, owner, and decision. |
How is idempotency different from a duplicate-send rule?
Idempotency handles retry safety for one intended create-mail request. A duplicate-send rule checks whether a similar person, household, address, campaign type, or review window has already mailed. Direct-mail workflows usually need both controls.
For example, an idempotency key can prevent one abandoned-cart event retry from creating two records. A duplicate-send rule can still catch a different event that tries to mail the same household inside a review window. For the broader rule, see the duplicate-send prevention guide.
How should idempotency connect to event payloads and campaign IDs?
The idempotency record should point to the event payload and campaign ID so operators can trace the request from source event to mailing decision, proof version, batch state, tracking joins, and later review.
For the source data contract, see the event payload guide. For the campaign-level join key, see the campaign ID guide. The idempotency key is not a replacement for either one; it is the retry-safety layer that keeps one intended request from multiplying.
What should an idempotency key not prove?
An idempotency key should not prove delivery, recipient exposure, response, attribution, revenue, or lift. It only shows that a workflow recognized repeated attempts for the same intended request and returned a consistent operational state.
Keep each record honest. The idempotency key handles retry safety. The send rule handles eligibility. The proof handles creative review. The batch handles release. Tracking fields support mailstream review. Measurement records handle outcome analysis.
What should a Sendvo-style workflow keep visible?
A Sendvo-style workflow should keep idempotency keys visible beside event payloads, send rules, suppression results, proof versions, campaign IDs, batch IDs, tracking fields, and audit timestamps before the mailing is reviewed.
Sendvo is in beta, so product language should stay capability-framed. The operational pattern is stable: when teams connect audience data, postcard design, triggered sends, and USPS tracking, idempotency records help retries stay explainable before physical mail moves forward.
FAQ
What is an idempotency key for direct mail APIs?
An idempotency key for a direct mail API is a stable value attached to a create-mail request so a retry can return the original result instead of creating another mail record. It should connect the source event, payload, recipient key, campaign ID, request state, and audit timestamps.
Is an idempotency key the same as a duplicate-send rule?
No. An idempotency key handles retry safety for one request. A duplicate-send rule checks whether a similar person, household, address, campaign, or review window has already mailed. Direct-mail workflows usually need both controls.
Should a retry create another postcard?
A retry should not create another postcard when the first request was already accepted under the same idempotency key. The workflow should return the original accepted, held, rejected, or released state and keep an audit record of the retry.