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
airposton yourPATH. See Install the CLI.- An engine running.
jq1.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
#!/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.
41 news@substack.example m_91c...
23 deals@shop.example m_0a7...
12 digest@forum.example m_5be...
Unsubscribe and archive
#!/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:
method | What happens | ok |
|---|---|---|
one-click | The engine makes the RFC 8058 POST. | true when the list’s server answered 2xx |
mailto | The engine queues the unsubscribe message from your account; taskId is its send task. | true once queued |
web | Nothing 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
archivewithtrashin the apply script. - Through an agent. The MCP
unsubscribetool 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