Find the Gmail newsletters you never open, and decide which to drop

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

Runs
Saturdays at 10:00
Uses
Gmail
Posts
Asks you

From your apps to your board

How the skill works: your agent reads recent mail from Gmail, saturdays at 10:00, and gives you a question for you and a telegram ping and the report in the chat.

Reads

  • GmailRecent mail
reads
Your agentClaude Code, Codex, Cursor or GeminiSaturdays at 10:00
posts

You get

  • A question for youOn your board, answered with a tap
  • A Telegram pingOnly when it needs your answer, if you connect Telegram
  • The report in the chatEvery run, with or without Briefkin

What you get

  • 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.

The card on the right is a sample. Yours shows your own numbers and updates in place every run.

What lands on your board

InboxGmail unsubscribe candidates · Claude Code

9 newsletters you have not opened in 30 days

Which ones do you want to drop? I will give you each unsubscribe link; nothing changes in your inbox until you click.

9 senders sent you 61 emails this month and you opened none. The top 5 account for 40 of them.

SenderEmails (30 days)OpenedOne-click
Weekly Growth Digest120Yes
Acme Outlet deals90Yes
DevTools Roundup80Yes
SaaSConf updates70No, link
Pricing Pulse40Yes
Resolve
An example with made-up numbers. Your agent posts your real ones.

What it does

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.

How it works

  1. 1List recent mail

    users.messages.list with q: "newer_than:30d -in:sent -in:chats" and maxResults: 500, following nextPageToken.

  2. 2Read the headers

    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. 3

    3Group 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. 4Check further back

    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. 5

    5Ask 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.

  6. Post it to the board

    With BRIEFKIN_TOKEN set, the agent sends the result as one card that updates in place every run. Without it, you get the report in the chat.

Install and run it

Pick your agent, where the data comes from and how to schedule it; the commands below follow.

Agent
Data
Schedule
  1. Install the skill

    One command. It puts the SKILL.md in ~/.claude/skills and in ~/.agents/skills, which Codex, Cursor, Gemini CLI, Copilot CLI and OpenCode read too.

    shellcurl -fsSL https://briefkin.dev/skills/gmail-unsubscribe-candidates/install | sh
  2. Run it

    Ask Claude Code:

    promptRun the gmail-unsubscribe-candidates skill

    Or paste the prompt instead of installing:

    promptLook at my Gmail from the last 30 days (newer_than:30d, not sent, not chats) and read only the headers: From, List-Id, List-Unsubscribe and List-Unsubscribe-Post, plus whether each message is still unread. Keep messages with a List-Unsubscribe header and group them by List-Id or sender. List senders that sent at least 3 emails I never opened, after checking I opened nothing from them in the last 90 days. Rank by volume, say which support one-click unsubscribe, and ask me which ones to drop. Then give me the unsubscribe links for the ones I pick. Do not unsubscribe, delete, label or filter anything yourself.
  3. Put it on a schedule

    Saturdays at 10:00, from cron on any machine where Claude Code is signed in:

    crontab0 10 * * 6 claude -p "Run the gmail-unsubscribe-candidates skill"

    Add it with crontab -e. A laptop asleep at that time runs it when it wakes if you use launchd or Task Scheduler instead; GitHub Actions works for the API route.

  4. Send it to your board

    Connect Briefkin once with curl -fsSL https://briefkin.dev/install | sh and every run lands on your board as a question for you. How setup works

View the SKILL.mdRaw file
SKILL.md---
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

What your agent needs

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

Connecting Gmail

  1. Claude's Gmail connector. In Claude, connect Gmail from the connector directory with your Google account to search and read your mail.
  2. Gmail MCP server, Google's own remote server at https://gmailmcp.googleapis.com/mcp/v1, in developer preview with the other Google Workspace MCP servers. It needs an OAuth client in Google Cloud set up for an AI agent (setup).
  3. Gmail API with OAuth. Create a desktop OAuth client, authorize once with the gmail.readonly scope, and store GMAIL_CLIENT_ID, GMAIL_CLIENT_SECRET and GMAIL_REFRESH_TOKEN. Publish the OAuth app (or make it Internal in Workspace): refresh tokens from an app left in Testing expire after seven days.

gmail.readonly can search and read but not send, delete or relabel; add gmail.compose only if you want the agent to leave drafts.

Questions

Why doesn't it unsubscribe for me?

Unsubscribing sends a request on your behalf to a third party, and a few senders use the click to confirm your address is live. Keeping the skill read-only means one scope (gmail.readonly) and no surprises; you click the links you chose, which takes a minute.

What counts as opened?

A message that is no longer marked unread. If you mark newsletters as read without opening them, or read them in a feed reader, the count will be off; in that case, base the rule on whether you ever clicked through, which the skill cannot see, or keep a list of senders to ignore.

Do I need Briefkin to use the Gmail unsubscribe candidates skill?

No. The skill runs with your own agent and gives you the report in the chat. With a Briefkin token set, each run also posts it to your board as a asks you, so you can glance at it instead of asking again.

Which agents can run it?

Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot CLI, OpenCode, Windsurf and Amp all read SKILL.md files. The install command puts it in ~/.claude/skills and ~/.agents/skills, where they look. ChatGPT, the Claude app and Grok take the prompt instead. Pick your agent under "Install and run it" and the commands change to match.

Can it work without an API or MCP server, from my browser?

Yes. Switch the data source to "Your browser" and the steps change to the Gmail pages themselves: the agent opens mail.google.com in a browser you are signed in to and reads the numbers off the page. Claude Code, Codex, Cursor, Claude app and ChatGPT can drive a browser out of the box; Gemini CLI, Copilot CLI and OpenCode need a Playwright or Chrome DevTools MCP server first. It is slower than the API and needs you signed in, so it suits a report you run by hand or from a scheduler on your own computer.

Answer your agents from one board, or from Telegram

Skills are free to use with any agent. Briefkin is where their results land: one board for every report, number and question your agents send, with a ping when something needs you.

Free during the open beta. No card.