Safe mutations

Retry the business action, not an uncertain network write.

Marmunk binds each idempotency key to canonical send semantics within one tenant and operation.

The contract

An identical retry returns the original msg_* resource. The retry itself receives a new req_* because it is a new API attempt.

Reusing the key with changed recipients, subject, content, sender, or attachments returns 409 idempotency_conflict.

Choose stable business keys

receipt:v1:order_8291
password-reset:v1:reset_48f2
invite:v2:wedding_12:guest_93

Keep keys deterministic, non-secret, and bounded. Do not generate a new UUID on each retry; doing so defeats idempotency.

Treat unknown as a safety state

Never blindly replay unknown. Marmunk uses this state when a provider write may have succeeded but the response was lost. Inspect the message trace and reconcile before another send.