1 files changed, 31 insertions, 2 deletions
diff --git a/src/mailman/rules/docs/header-matching.rst b/src/mailman/rules/docs/header-matching.rst
index 7b2d8c6d7..e3f9f9ab2 100644
--- a/src/mailman/rules/docs/header-matching.rst
+++ b/src/mailman/rules/docs/header-matching.rst
@@ -119,8 +119,14 @@ List-specific header matching
 =============================
 
 Each mailing list can also be configured with a set of header matching regular
-expression rules.  These are used to impose list-specific header filtering
-with the same semantics as the global `[antispam]` section.
+expression rules.  These can be used to impose list-specific header filtering
+with the same semantics as the global `[antispam]` section, or to have a
+different action.
+
+To follow the global antispam action, the header match rule must not specify a
+`chain` to jump to. If the default antispam action is changed in the
+configuration file and Mailman is restarted, those rules will get the new jump
+action.
 
 The list administrator wants to match not on four stars, but on three plus
 signs, but only for the current mailing list.
@@ -168,3 +174,26 @@ As does a message with a spam score of four pluses.
     Rule hits:
         x-spam-score: [+]{3,}
     No rules missed
+
+Now, the list administrator wants to match on three plus signs, but wants those
+emails to be discarded instead of held.
+
+    >>> mlist.header_matches = [
+    ...     HeaderMatch(header='x-spam-score', pattern='[+]{3,}', 'discard')
+    ...     ]
+
+A message with a spam score of three pluses will still match, and the message
+will be discarded.
+
+    >>> msgdata = {}
+    >>> del msg['x-spam-score']
+    >>> msg['X-Spam-Score'] = '+++'
+    >>> del msg['message-id']
+    >>> msg['Message-Id'] = '<dee>'
+    >>> with event_subscribers(handler):
+    ...     process(mlist, msg, msgdata, 'header-match')
+    DiscardEvent discard <dee>
+    >>> hits_and_misses(msgdata)
+    Rule hits:
+        x-spam-score: [+]{3,}
+    No rules missed