---
name: gmail-unsubscribe-candidates
description: "Every Saturday: the newsletters and promotional senders in your Gmail you have not opened in 30 days, ranked by volume, with their unsubscribe links. Use when the user asks for this, or when it runs on a schedule."
---

# Gmail unsubscribe candidates

Every Saturday: the newsletters and promotional senders in your Gmail you have not opened in 30 days, ranked by volume, with their unsubscribe links.

Most inbox clutter comes from a short list of senders you once signed up for and now archive on sight. Gmail offers an unsubscribe link at the top of each message, but nobody works through them one by one, and the list keeps growing.

Once a week the agent looks at the last 30 days of mail that carries an unsubscribe header, counts how much each sender sent and how much of it you opened, and lists the ones you never read. You choose; it hands you the links. It reads only, so nothing is unsubscribed, deleted or filtered without you.

## Two ways to get the data

Use the API or MCP route when you have an MCP server, a CLI or an API token for the app. Otherwise, if you can drive a browser the user is signed in to (Claude in Chrome, a Playwright or Chrome DevTools MCP server), use the browser route. Say which one you used.

## Route A: API or MCP server

### What you need

- A Gmail connector or MCP server, or Gmail API OAuth with `gmail.readonly`. The skill reads only; it never unsubscribes, deletes or creates filters.

If something is missing, say what and stop; do not invent numbers.

### Steps

1. **List recent mail** (Gmail): `users.messages.list` with `q: "newer_than:30d -in:sent -in:chats"` and `maxResults: 500`, following `nextPageToken`.
2. **Read the headers** (Gmail): `users.messages.get` with `format: metadata` and `metadataHeaders` `From`, `List-Id`, `List-Unsubscribe` and `List-Unsubscribe-Post`, in batches. Keep messages with a `List-Unsubscribe` header; note whether `UNREAD` is among their `labelIds`.
3. **Group by sender**: Group by `List-Id`, or by the sender address when there is none. For each, count messages in 30 days and how many you opened (no longer `UNREAD`). A candidate sent at least 3 and you opened none.
4. **Check further back** (Gmail): For each candidate, search `from:<address> newer_than:90d -is:unread` and drop it if you opened anything in 90 days; some newsletters are read in bursts.
5. **Ask which to drop**: Post an action card ranked by volume, marking senders that support one-click unsubscribe (`List-Unsubscribe-Post: List-Unsubscribe=One-Click`). When you answer, reply with the unsubscribe links or addresses for the ones you picked.

## Route B: the browser

### What you need

- Signed in to the Gmail account at mail.google.com. Manage subscriptions is rolling out gradually; if the **More** menu does not show it, start from a search for `newer_than:30d is:unread category:promotions` instead.

If something is missing, say what and stop; do not invent numbers.

### Steps

Start at https://mail.google.com/. The user is signed in already; never type passwords or codes, and ask if a sign-in page appears.

1. **Open Manage subscriptions**: In the left panel click **More**, then **Manage subscriptions**. Gmail lists the senders that mail you regularly with the number of emails each sent recently, and an **Unsubscribe** button beside each. Read the names and counts; do not click Unsubscribe.
2. **Check whether you open them**: For each sender with 3 or more emails, click the name to open its messages, or search `from:<address> newer_than:30d -is:unread`. No results means you opened nothing from them in 30 days.
3. **Look further back**: For each remaining candidate search `from:<address> newer_than:90d -is:unread`. Any result drops the sender from the list; some newsletters get read in bursts.
4. **Rank and ask**: Order the candidates by emails in 30 days. Open one message from each and note whether the **Unsubscribe** link next to the sender name is present (Gmail shows it when the sender supports one-click). Ask which to drop and hand over the links.

Note: Manage subscriptions shows a recent count without naming the window, so the 30-day figure comes from the search. The page is only on Gmail for desktop web and is not available to everyone yet. Workspace accounts whose admin disabled the feature fall back to search, which still works.

## The report

- **Candidates**: sender, emails in 30 days, opened (none), and whether one-click unsubscribe is supported.
- **Volume**: how many emails these senders sent you this month.
- The ask: which to drop, then the links for the ones you choose.

## Post it to Briefkin

When `BRIEFKIN_TOKEN` is set, or `~/.config/briefkin/env` exists (the installer from https://briefkin.dev/docs writes it), also send the result to the user's Briefkin board as one card. Keep the `item_key` the same on every run so the card updates in place, use a new `event_id` per run, and put today's real numbers in place of the example ones. If the request fails, say so once and carry on.

```bash
[ -n "${BRIEFKIN_TOKEN:-}" ] || . ~/.config/briefkin/env
curl -sS -X POST "${BRIEFKIN_URL:-https://briefkin.dev}/v1/events" \
  -H "authorization: Bearer $BRIEFKIN_TOKEN" \
  -H "content-type: application/json" \
  -d @- <<'JSON'
{
  "v": 1,
  "event_id": "gmail-unsubscribe-candidates/<date of this run, e.g. 2026-10-16>",
  "item_key": "gmail-unsubscribe-candidates",
  "project": "Inbox",
  "source": "Gmail unsubscribe candidates skill",
  "kind": "action",
  "title": "9 newsletters you have not opened in 30 days",
  "summary": "**9 senders** sent you **61 emails** this month and you opened none. The top 5 account for 40 of them.",
  "action": {
    "request": "Which ones do you want to drop? I will give you each unsubscribe link; nothing changes in your inbox until you click.",
    "options": [
      "Links for all 9",
      "Top 5 only",
      "Let me pick",
      "Keep them all"
    ]
  },
  "widget": {
    "type": "Table",
    "props": {
      "columns": [
        "Sender",
        "Emails (30 days)",
        "Opened",
        "One-click"
      ],
      "align": [
        "left",
        "right",
        "right",
        "left"
      ],
      "rows": [
        [
          "Weekly Growth Digest",
          12,
          0,
          "Yes"
        ],
        [
          "Acme Outlet deals",
          9,
          0,
          "Yes"
        ],
        [
          "DevTools Roundup",
          8,
          0,
          "Yes"
        ],
        [
          "SaaSConf updates",
          7,
          0,
          "No, link"
        ],
        [
          "Pricing Pulse",
          4,
          0,
          "Yes"
        ]
      ]
    }
  }
}
JSON
```

Widgets come from the Briefkin catalog (https://briefkin.dev/v1/catalog). Without a token, just give the user the report.

## Run it on a schedule

Suggested: Saturdays at 10:00 (`0 10 * * 6`). From cron, with the agent signed in on that machine:

```bash
0 10 * * 6 claude -p "Run the gmail-unsubscribe-candidates skill"
# Codex: codex exec, Gemini CLI: gemini -p, Copilot CLI: copilot -p, OpenCode: opencode run
```

Or use the agent's own scheduler (Claude Code routines, Codex automations, Claude or ChatGPT scheduled tasks): https://briefkin.dev/skills/gmail-unsubscribe-candidates#schedule

Source: https://briefkin.dev/skills/gmail-unsubscribe-candidates
