List-Unsubscribe Header Requirements for Bulk Senders
Bulk senders now need unsubscribe headers in their infrastructure, not templates.
List-Unsubscribe compliance for bulk senders is a complete sending-system requirement. It depends on correct message classification, a POST-capable HTTPS endpoint, DKIM coverage, and suppression processing within 48 hours. If one part is missing, mail that would once have gone to spam can now be rejected for good, so automated pipelines need to enforce the rules before sending, when warnings can still stop the send.
Why List-Unsubscribe compliance became a hard technical requirement for bulk senders
Bulk senders can no longer treat unsubscribe support as a deliverability improvement to address after the sending system works. Under these rules, non-compliant bulk mail that once went to spam is now rejected for good. A message can be composed correctly for its reader and still fail because its unsubscribe mechanism is incomplete.
The requirement therefore belongs in sending infrastructure. A template may supply a header, but it cannot establish whether the receiving endpoint works or whether suppression updates reach the next send.
Which messages require List-Unsubscribe headers and which do not
The unsubscribe requirement applies only to marketing and subscribed messages. That distinction is an operational classification problem because it determines which rules the sending pipeline must apply. Classification must precede header injection. Otherwise, the pipeline has already made a compliance decision before it knows what kind of message it is sending.
The transactional exemption does not depend on the label chosen by the sender. A message labeled “transactional” that contains promotional content is treated as marketing by providers. Content determines the category, so a pipeline cannot safely use the sender’s preferred label as a substitute for that distinction. The same principle matters when an automated system constructs messages outside established templates.
An agent that strips headers from every message to simplify templates removes required unsubscribe support from marketing sends. An agent that adds unsubscribe headers to every message, including password resets, creates a different compliance exposure.
The two specific headers that satisfy one-click unsubscribe
For qualifying marketing and subscribed messages, one-click unsubscribe requires both List-Unsubscribe and List-Unsubscribe-Post. The first contains the HTTPS URL for the unsubscribe endpoint. The second supplies the companion header required for the one-click mechanism. Sending only one header, or sending both incorrectly, does not satisfy the requirement.
Both headers must be in the raw message source of every send that needs them. A rendered preview shows the message as content and leaves the presence of the headers delivered with it unverified. Checks must therefore cover the raw headers and the values they have after template rendering. The presence of a header name alone does not establish that its value is usable.
Gmail populates its native “Unsubscribe” button from these headers at the top of the email interface. When they are missing, that route is unavailable and users are pushed toward “Report Spam” instead. That alternative damages sender reputation more directly. Header correctness consequently affects both compliance and the path recipients can take when they no longer want the mail.
What the HTTPS endpoint behind the header must actually do
The HTTPS URL in List-Unsubscribe must point to a machine-callable endpoint. That endpoint must accept a POST request and carry out the unsubscribe without a person taking part. A destination that requires a recipient to finish the process does not provide the required header-based mechanism. This part requires working server-side behavior.
A preference center can still serve recipients who want to change frequency or topics. It can appear in the email body, but it must not be the only route available through the header mechanism. Treating them as interchangeable leaves the one-click requirement unfinished.
The endpoint should act only on POST requests. Link scanners automatically follow URLs in email, so an endpoint that also unsubscribes on GET can remove a recipient before the message is seen. Restricting the action to POST avoids that particular source of spurious unsubscribes. Once a real request arrives, though, the unsubscribe must be carried out within the 48-hour processing window.
Why DKIM coverage of both headers is a non-negotiable part of the specification
A working endpoint and two present headers are still insufficient without DKIM coverage. Both List-Unsubscribe and List-Unsubscribe-Post must be in the DKIM signature’s signed header set. Without that coverage, receivers should withhold the one-click unsubscribe action for that message because the integrity of the unsubscribe headers in transit is unverified.
DKIM signs only the headers in a defined set, which may leave other headers in the message unprotected. If the two unsubscribe headers are absent from the signed header list in the h= tag, the cryptographic guarantee does not extend to them. General confidence that a sending system uses DKIM is not enough to establish this narrower requirement.
This is a configuration detail at the ESP or sending infrastructure level. Developers who work at the application layer may supply the right headers without checking how the infrastructure signs them. As a result, coverage can be silently wrong while the message appears to deliver normally. Checks of the raw headers must show which ones are in the signed set.
The 48-hour processing window and what it requires of suppression infrastructure
Honoring an unsubscribe within 48 hours requires more than accepting and recording the request. The suppression list must get the signal in time to stop later sends. An endpoint can accept and record the request while the backend still fails to act on the recipient’s choice.
Consider an unsubscribe that arrives successfully and is logged while suppression updates wait for a batch process. The next scheduled send can leave the queue before that batch runs. Suppression lag then produces another message to an opted-out address, which can trigger a complaint. Complaint accumulation can lead to a rate breach and, in turn, rejections.
Suppression checks must use state current at send time, even when a snapshot was captured when the campaign was created. Any unsubscribe received between those moments makes the earlier snapshot stale. A global suppression list checked at the API layer before a send is accepted provides the appropriate enforcement point.
How automated sending pipelines introduce List-Unsubscribe failure modes that human senders do not
Automated pipelines expose weaknesses in implementations that assume a person reviews each send. Agents do not provide that review, and message construction can proceed even when a compliance field is unusable. A message can have headers and be sent successfully while its unsubscribe mechanism still fails to work.
A recognizable example is a template that leaves {{unsubscribe_url}} literally in the header value. The header is present, but its value is a malformed URL that can return an error on POST or point nowhere. The send can succeed while the defect remains invisible until a provider flags it. Dynamically constructed messages introduce a related omission risk when an agent builds the message field by field and leaves out headers that a template system would normally include.
Burst processing creates a different problem because it compresses many sends into a short window. If an unsubscribe arrives during the burst, the suppression update races against the remaining queued sends. Resolving this race depends on the current-state suppression checks described above.
Messages already sent also need the infrastructure to keep working after an agent finishes its task. Scheduled endpoint deprovisioning or token rotation can invalidate the unsubscribe URLs in those messages, making past campaigns non-compliant retroactively. The endpoint must therefore stay live and respond to requests across agent execution cycles. Separately, business-event-derived idempotency keys should prevent retry duplicates so that retry behavior does not produce additional sends.
Why pre-send linting at the API layer is the correct place to enforce List-Unsubscribe compliance
If a missing List-Unsubscribe-Post header is detected after a campaign leaves the system, the opportunity to stop those sends has passed. The sender’s reputation may already be damaged, and complaints may already be adding up. For automated pipelines operating at volume, the useful intervention point is before the API accepts the send.
A pre-send linting layer should validate the presence and syntax of both required headers. It should also check that the HTTPS URL is well-formed rather than an unrendered template variable, and that the recipient is not on the suppression list. These checks place enforcement at the boundary every outgoing request must cross.
The response to a failed check also matters for an automated caller. A machine-readable error that identifies the malformed field and the required correction gives an agent a basis for fixing the request and retrying. A logged warning that the agent cannot parse does not provide the same control. Compliance should consequently be enabled by default, with the platform injecting the required headers, validating them, and refusing sends that cannot be made compliant.
AgentiSend combines transactional and marketing sends in a single API, which brings both message types under one integration. That gives developers one place to manage header injection rules, suppression checks, and compliance validation, without separate integrations to keep up. Common enforcement must still preserve the classification distinction rather than attach unsubscribe headers indiscriminately. Pre-send validation also does not replace the separate obligations to maintain endpoint availability, configure DKIM coverage, and process suppression updates.
A practical compliance checklist for bulk senders implementing List-Unsubscribe
Check classification first. Marketing and subscribed messages require the unsubscribe mechanism, while truly transactional messages do not. Messages with promotional content must meet the requirement even if they have a transactional label. Apply the header rules only after that distinction has been made.
Check the raw message source for both List-Unsubscribe and List-Unsubscribe-Post. Validate their syntax and reject unresolved template variables before accepting the send. Check that the unsubscribe URL uses HTTPS and points to a POST-capable endpoint that completes the action without human interaction. Keep any preference center as a separate option.
Check that both unsubscribe headers appear in the DKIM signature’s h= signed header list. Confirm that GET requests do not trigger unsubscribes and that the endpoint remains live across agent execution cycles. Include token rotation and endpoint deprovisioning in that availability check. A compliant message at dispatch still needs a usable unsubscribe route afterward.
Check that unsubscribe processing takes no more than the required 48-hour window and updates suppression before the next send cycle. Check the current global suppression list at the API boundary, since a snapshot from when the campaign was created may be out of date. Use business-event-derived idempotency keys to prevent retry duplicates, and return machine-readable errors for rejected requests.
