NOTMUCH-ADDRESS(1)

📦
version 0.40 · 13 versions
, in fedora 44, nixos 26.05, ubuntu resolute

🌸 NOTMUCH-ADDRESS — the "who even are these people" command ✨

okay bestie, welcome to notmuch-address from the notmuch manual, version 0.40 — yes I folded the manual name in up top like a little name tag, you're welcome 🎀

💌 NAME

notmuch-address — it spits out addresses from the messages that match your search. that's the whole vibe 💅

🦋 SYNOPSIS

notmuch address [option ...] <search-term> ...

✨ DESCRIPTION

So here's the tea ☕ — you give it some search terms, it finds every message that matches, and then it shows you the addresses hiding in those messages. And because nobody wants to see the same address forty-seven times, duplicate addresses get filtered out. obsessed. 🫶

If you wanna know what syntax you can actually put in those <search-terms>, go read notmuch-search-terms — that's where the whole grammar situation lives, iykyk.

The options it supports are giving very demure, very mindful:

  • --format=(json|sexp|text|text0) — pick how your results come out:
    • json — JSON, obviously
    • sexp — S-Expressions
    • text — plain text separated by newline characters. this is the default, no cap
    • text0 — plain text separated by null characters, which is the move if you're piping into xargs(1) with its -0 option (where that option exists on your system, bestie, it's not everywhere 💀)
  • --format-version=N — use this specific version of the structured output format. it's meant for programs that call notmuch internally, so like, tooling, not you-and-your-terminal-at-2am. if you skip it, the latest supported version gets used. slay ✨
  • --output=(sender|recipients|count|address) — controls what info actually shows up in the output. and here's the cute part: you can pass this option multiple times to mash different outputs together 💖. and if you give it neither --output=sender nor --output=recipients, then --output=sender is just implied. it chose for you. main character behavior 👑
    • sender — output every address from the From header.
Note: searching for sender should be way faster than searching for recipients, because sender addresses are cached directly in the database, whereas the other addresses have to be fetched from the message files. so, like, speedrun strats 🏃♀️
  • recipients — output every address from the To, Cc and Bcc headers.
  • count — print how many times each address was encountered during the search.
Note: with this option, addresses only get printed after the whole search is finished. this may take a long time. like, go make a snack, fr fr 😭
  • address — output only the email addresses, instead of the full mailboxes with names and email addresses attached. heads up though: this option does nothing for the JSON or S-Expression output formats. it just sits there. no thoughts, head empty 🐚
  • --deduplicate=(no|mailbox|address) — controls how results get deduplicated, aka how we stop the same person showing up like twelve times.
    • no — output all occurrences of addresses in the matching messages. absolutely no filtering. but heads up, this one is not applicable with --output=count. 🚫
    • mailbox — deduplicate based on the full, case sensitive name and email address — a whole mailbox. this is basically the same as piping the --deduplicate=no output into sort | uniq, except the order of results is different. and guess what, this is the default. the moment. the icon. ⭐
    • address — deduplicate based on the case insensitive address part of the mailbox. of all the variants (different name, different case, whatever), it prints the one occurring most frequently among the matching messages. and if --output=count is specified, it includes all the variants in the count. thorough queen 🌈
  • --sort=(newest-first|oldest-first) — present results either chronologically (oldest-first) or reverse chronologically (newest-first).

By default, results show up in reverse chronological order, meaning the newest results come first. fresh off the press 💅

BUT — and this is the plot twist — if either --output=count or --deduplicate=address is specified, this option gets ignored and the order of the results is unspecified. so don't come for me when the order's weird, it said what it said 🙈

  • --exclude=(true|false) — okay so a message is called "excluded" if it matches at least one tag in search.exclude_tags that does not appear explicitly in the search terms. this option decides whether excluded messages get omitted from the search process.

The default value, true, prevents excluded messages from matching the search terms. keep them out, we don't know them 🚪

false allows excluded messages to match search terms and appear in the displayed results. let them in, invite the chaos 🎉

🚦 EXIT STATUS

This command supports these special exit status codes, and yes they're very specific:

  1. 20 — the requested format version is too old. grandmacore 👵
  2. 21 — the requested format version is too new. stop living in the future bestie 🔮

👀 SEE ALSO

your reading list, go off 📚:

  • notmuch
  • notmuch-config
  • notmuch-count
  • notmuch-dump
  • notmuch-hooks
  • notmuch-insert
  • notmuch-new
  • notmuch-reply
  • notmuch-restore
  • notmuch-search
  • notmuch-search-terms
  • notmuch-show
  • notmuch-tag

👑 Author

Carl Worth and many others — legends, every single one 💜

2009-2026, Carl Worth and many others

and that's the whole page babes 🎀 this was notmuch-address, version 0.40, dated Jan 31, 2026 — go find those addresses, you got this 🦋💖✨

📦 where this page comes from