--- /dev/null
+# Message exclusion and deletion
+
+An important principle of notmuch is that it does not modify your mail
+(with the one exception of
+[[maildir flag syncing|howto/#sync_maildir_flags]]). A question that
+frequently comes up, though, is how users can delete messages. While
+notmuch does not support, nor ever will, the deleting of messages,
+notmuch has a couple of nice features that allow users to handle
+excluding unwanted messages in a sensible way.
+
+## <span id="exclude>**message exclusion**</span>
+
+Notmuch has the ability to exclude message with certain tags from
+search results. A common usage is to exclude "deleted" or "spam"
+messages so that they don't clutter your search results. To enable
+excludes, use the config utility:
+
+ $ notmuch config set search.exclude_tags deleted spam
+
+This will cause messages with the "deleted" or "spam" tags to be
+excluded from search results.
+
+It is still possible to find messages with excluded tags, though, by
+manually including the excluded tag in your search:
+
+ $ notmuch search from:foo and tag:spam
+
+This will find messages from "foo" with the tag "spam", even though
+"spam" is an excluded tag.
+
+## <span id="files">**message files**</span>
+
+Notmuch makes it very easy to access the underlying mail files
+associated with specific search terms using the "file" output format
+of notmuch search. To find all message files associated with the tag
+"foo" rung:
+
+ $ notmuch search --output=files tag:foo
+
+This will output the paths to all message files with "tag:foo", one
+per line.
+
+This is useful in a number of different ways. For instance, it could
+be used to train a spam filter:
+
+ $ notmuch search --output=files tag:spam | sa-learn -f -
+
+It can also be used to purge mail files from disk:
+
+ $ notmuch search --output=files tag:deleted | xargs -l rm
+
+Make sure you run "notmuch new" after the last command so the database
+becomes aware that the files have been removed and can remove the
+corresponding entries from the index.
+
+## <span id="recipe>**putting it all together**</span>
+
+So if you want to add message deletion to your work flow, here's a
+procedure:
+
+* Add exclusion for messages with the "deleted" tag:
+
+ $ notmuch config set search.exclude_tags deleted
+
+* Add a key binding to your favorite ui to add a "deleted" tag to
+ messages that you want to delete. In [[emacs|emacstips]] that might
+ be:
+
+ (define-key notmuch-show-mode-map "d"
+ (lambda ()
+ (interactive)
+ (notmuch-show-tag "+deleted")))
+
+* And, finally, if you _really_ want the messages purged from disk,
+ you can delete them manually with:
+
+ $ notmuch search --output=files tag:deleted | xargs -l rm