Airpost
Terminal and scripting

Bulk unsubscribe

Find the mailing lists you get the most mail from and unsubscribe from them with airpost unsubscribe, then archive what's left.

What you’ll build

A two-step script. The first step lists the senders of your recent mailing-list mail, with counts, into a file you edit. The second unsubscribes from every list you kept in that file, using each message’s List-Unsubscribe header, and archives that sender’s threads. You decide which lists go; the script does the clicking.

Prerequisites

  • airpost on your PATH. See Install the CLI.
  • An engine running.
  • jq 1.6 or later.

airpost unsubscribe can send mail: when a list only offers a mailto: address, the engine sends the unsubscribe message from your account. When a list only has a web page, it prints the link for you to open.

List candidate senders

~/bin/unsub-candidates
#!/usr/bin/env bash
# Write senders of list mail from the last N days to unsub.tsv:
#   count <TAB> sender <TAB> a message id that carries List-Unsubscribe
set -euo pipefail
days="${1:-60}"
out="${2:-unsub.tsv}"

airpost search "in:inbox after:${days}d" -n 1000 --json | jq -r '.threads[].id' |
while read -r thread; do
  airpost show "$thread" --json | jq -r '
    .messages[]
    | select(.hListUnsub != null and (.draft | not))
    | [(.from[0].email // ""), .id] | @tsv'
done |
sort | awk -F'\t' '
  { n[$1]++; id[$1] = $2 }
  END { for (s in n) printf "%d\t%s\t%s\n", n[s], s, id[s] }' |
sort -rn > "$out"

echo "wrote $(wc -l < "$out") senders to $out"
chmod +x ~/bin/unsub-candidates
~/bin/unsub-candidates 60

Edit the list

Open unsub.tsv and delete the lines for lists you want to keep. Every line left will be unsubscribed.

unsub.tsv
41	news@substack.example	m_91c...
23	deals@shop.example	m_0a7...
12	digest@forum.example	m_5be...

Unsubscribe and archive

~/bin/unsub-apply
#!/usr/bin/env bash
# Unsubscribe from each sender in the file, then archive their inbox threads.
set -uo pipefail
file="${1:-unsub.tsv}"
web=()

while IFS=$'\t' read -r count sender msg; do
  [ -z "$msg" ] && continue
  r=$(airpost unsubscribe "$msg" --json)
  status=$?
  method=$(jq -r '.method // "?"' <<<"$r" 2>/dev/null)
  if [ $status -ne 0 ]; then
    echo "FAILED  $sender ($method): $(jq -r '.error // empty' <<<"$r" 2>/dev/null)"
    continue
  fi
  case "$method" in
    web) web+=("$sender  $(jq -r '.url' <<<"$r")"); echo "WEB     $sender" ;;
    *)   echo "OK      $sender ($method)" ;;
  esac
  airpost archive -q "from:$sender in:inbox" -n 500 --json \
    | jq -r --arg s "$sender" '"        archived \([.accounts[].threadIds[]] | length) from \($s), undo \(.undo)"'
done < "$file"

if [ ${#web[@]} -gt 0 ]; then
  echo
  echo "Open these to finish unsubscribing:"
  printf '  %s\n' "${web[@]}"
fi
chmod +x ~/bin/unsub-apply
~/bin/unsub-apply unsub.tsv

Expected output

OK      news@substack.example (one-click)
        archived 41 from news@substack.example, undo 7d21...
OK      deals@shop.example (mailto)
        archived 23 from deals@shop.example, undo c90e...
WEB     digest@forum.example
        archived 12 from digest@forum.example, undo 1f4b...

Open these to finish unsubscribing:
  digest@forum.example  https://forum.example/unsubscribe?u=...

How it works

Messages in airpost show <thread-id> --json carry hListUnsub when the message had a List-Unsubscribe header, which is how the first script tells list mail from personal mail. airpost unsubscribe <message-id> picks the best method the list offers:

methodWhat happensok
one-clickThe engine makes the RFC 8058 POST.true when the list’s server answered 2xx
mailtoThe engine queues the unsubscribe message from your account; taskId is its send task.true once queued
webNothing is sent; url is the page to open.always true

When ok is false the command exits 1 and error says why. --method one-click|mailto|web restricts it to one way, for example --method one-click to never send mail on your behalf.

The archive step uses --query per sender; its result’s undo token reverses that archive with airpost undo <token>. Unsubscribing itself can’t be undone.

Variations

  • Archive without unsubscribing. Keep the list but get it out of the inbox: airpost rules add --name Newsletters --if 'from contains substack.example' --then archive (Gmail; on other accounts use --then 'move Newsletters').
  • Trash instead. Replace archive with trash in the apply script.
  • Through an agent. The MCP unsubscribe tool does the same and needs the Read, draft and send level.

Cleanup

rm unsub.tsv ~/bin/unsub-candidates ~/bin/unsub-apply
airpost undo --list -n 20      # to bring archived threads back