Build the one-click unsubscribe endpoint idempotently: duplicate POSTs should not resurrect or error on an opt-out

Separate the transport fact from reputation guesses

RFC 8058 specifies an HTTPS URI in List-Unsubscribe and a POST whose body contains List-Unsubscribe=One-Click. The URL must encode enough information to identify the recipient and list without relying on an interactive confirmation exchange.

A one-click unsubscribe endpoint can receive the same valid request more than once. Mailbox providers may retry after a timeout, users can trigger multiple paths, and your own queue can replay work after a crash. The endpoint should therefore be idempotent: the first valid POST creates or confirms suppression, and later equivalent POSTs return success without creating a second campaign state or accidentally re-enabling the recipient. Idempotency is especially important when suppression fans out to several mailboxes, because duplicate events should converge on one global stop state rather than racing to update separate campaign records.

How a green checker can still hide the problem

Because the user action is conceptually one click, developers sometimes assume the endpoint will receive exactly one request. Distributed systems can retry, and security scanners or receiver infrastructure can exercise URLs in unexpected patterns.

Do not require a browser session, CSRF cookie, login, or confirmation page on the RFC 8058 machine endpoint. Those controls are appropriate for interactive account changes, but they can make mailbox-provider one-click POSTs fail. Security instead comes from the signed message headers, an HTTPS endpoint, and an opaque recipient-specific token or equivalent design that does not expose arbitrary account operations. Also avoid returning an error merely because the recipient is already suppressed; from the caller’s perspective, the requested final state has already been achieved.

Recreate the failure with one controlled path

Send the same authenticated opt-out token repeatedly and concurrently in a staging environment. Assert every request leaves the same final suppression state and no request can re-enable a recipient.

Test idempotency by sending the same valid POST concurrently several times and again after the first request has committed. Exactly one durable suppression state should result, every safe repeat should receive the intended success behavior, and no follow-up jobs should remain authorized. Then test a malformed or expired token to ensure the endpoint does not suppress arbitrary addresses. Finally, simulate a database timeout after the write but before the HTTP response; a retry must observe the existing state rather than create inconsistent duplicates. This failure injection catches the real reason idempotency matters.

Make the smallest reversible change

Model suppression as a durable idempotent upsert with a first-seen timestamp and append-only event log. Return a stable success response for an already-suppressed valid token.

Keep the endpoint small and observable. Log a request identifier, recipient/contact key, token validation result, first-suppressed timestamp, and whether the call created or merely confirmed existing state. Do not log raw secret tokens. Push the resulting suppression into the same source of truth checked by send workers, not a separate “unsubscribe service” that syncs later. Monitoring should alert on sustained 4xx/5xx rates and latency because a technically correct header is useless if the endpoint is unavailable when receivers try to call it.

A practical mailbox or domain example

POST number one at 12:00 writes suppressed=true. POST number two at 12:00:01 should observe that state and succeed harmlessly, not delete a row, create a duplicate workflow, or throw “not found.”

Connect idempotency to queue cancellation transactionally where practical. Writing a suppression row and canceling future jobs in unrelated asynchronous systems can create a window where the endpoint returns success but a queued follow-up still sends. A robust design makes the shared suppression row authoritative: even if explicit queue cleanup lags, every worker checks suppression immediately before submission and refuses the message. Queue cleanup then becomes an efficiency operation rather than the only safety barrier. This architecture also handles replay gracefully. Ten duplicate unsubscribe POSTs may create ten log entries if desired, but they converge on one recipient state and no later send authorization. Test that invariant after migrations, because moving queues or databases is exactly when “two sources of truth” bugs tend to appear.

The minimum useful change record

Record token identifier without exposing sensitive recipient data in logs, first and repeat request times, endpoint result, suppression row version, and queued jobs cancelled after the first transition.

Conditions that should remain unknown or retryable

Do not require a browser cookie or sign-in page for the RFC 8058 machine POST. The endpoint is meant for automated one-click processing, with authentication encoded in the URL/token design.

Add an external synthetic check that performs a safe test unsubscribe against a dedicated fixture identity after deployments. Header generation, token validation, routing, database writes, and worker suppression can each succeed independently in unit tests while the full path is broken. A controlled end-to-end check proves the exact operation a mailbox provider depends on still reaches the shared stop state.

Field checklist

• Capture the raw evidence for RFC 8058 one click unsubscribe endpoint idempotent POST before editing DNS, queue state, or mailbox metadata.
• Confirm the cited mechanism using oneclick-rfc, gmail-faq rather than a generic deliverability score.
• Keep a known-good control case so the failing layer can be compared without changing several variables at once.
• Apply the narrow repair described for Build the one-click unsubscribe endpoint idempotently: duplicate POSTs should not resurrect or error on an opt-out and preserve a rollback or retry path.
• Repeat the original failing test after the change; do not substitute a different checker as proof of recovery.
• Store timestamp, affected identity, raw result, action taken, and the post-change result in the operator log.