What X-Spam Headers Are and Where They Live

When Spam Killer processes an inbound message, it adds custom headers to the message before forwarding it to your upstream mail server. These headers are part of the message envelope — they appear at the top of the raw message source alongside standard headers like From, To, Date, and Subject.

The two most important headers Spam Killer adds are:

X-Spam-Status — a human-readable summary of the filtering verdict. For a message that passed filtering, it looks like this:

X-Spam-Status: No, score=0.23 required=0.50 tests=BAYES_00,SPF_PASS,
    DKIM_VALID autolearn=ham autolearn_force=no version=3.4.6

For a message caught as spam:

X-Spam-Status: Yes, score=7.82 required=0.50 tests=BAYES_99,
    HTML_MESSAGE,MISSING_MID,RDNS_NONE,FROM_ADDR_WS
    autolearn=spam version=3.4.6

X-Spam-Score — a numeric-only header containing just the raw score, for easy parsing in mail rules:

X-Spam-Score: 7.82

Spam Killer also adds X-Spam-Flag: YES to messages above the threshold, and X-Spam-Report containing a detailed breakdown of which tests fired and their individual score contributions. The score is a floating point number; higher values indicate a higher spam probability. Spam Killer's default threshold is 0.50, but you can configure this per domain in your dashboard.

Using Score Thresholds to Build Tiered Rules

The score gives you more granularity than a simple yes/no spam verdict. A useful tiered approach:

  • Score > 0.80 (very likely spam): Move to spam folder or delete. At this threshold, false positives are extremely rare.
  • Score > 0.50 (likely spam, at or above threshold): Move to spam folder for review. The filter classified it as spam but the score is moderate.
  • Score 0.30–0.50 (borderline, below threshold): Optionally tag the subject line or apply a label. This is the grey area — some legitimate mail lands here, but it bears closer attention.

The right threshold depends on your tolerance for false positives vs. false negatives. Start with the defaults and adjust based on what ends up in your spam folder during the first two weeks.

1. Microsoft Exchange and Outlook: Transport Rules

In Exchange Online (Microsoft 365) and on-premises Exchange, you can create Transport Rules (now called Mail Flow Rules) that match on message headers.

In the Exchange Admin Center, navigate to Mail flow → Rules → Add a rule. Set the condition to "A message header includes" and enter:

  • Header name: X-Spam-Flag
  • Header value: YES

Set the action to "Deliver the message to the hosted quarantine" or "Set the spam confidence level (SCL) to 9" (which routes it to the Junk Email folder). You can also set the action to "Prepend the subject with" a tag like [SPAM] for borderline messages.

For score-based rules, use the condition "A message header matches" with header X-Spam-Score and a regex pattern. For example, to match scores above 0.8, you can use the pattern [89]\.\d+|[1-9]\d+\.\d+ — or, more robustly, use a Postfix-level rule (described below) and have Exchange trust the SCL set there.

In the desktop Outlook client, rules based on message headers are created under File → Manage Rules & Alerts → New Rule. Choose "Apply rule on messages I receive," then select "with specific words in the message header." Enter X-Spam-Flag: YES as the search phrase and set the action to move to the Junk Email folder.

2. Gmail and Google Workspace: Filters

Gmail's filter interface has a "Has the words" field that searches message content including headers. To filter on X-Spam headers, use the search syntax with the deliveredto or header search. Unfortunately, Gmail's standard filter interface does not expose raw header matching for custom headers.

The most reliable approach for Google Workspace is to use Google Workspace Admin → Apps → Google Workspace → Gmail → Compliance → Content compliance. Create a rule that matches on the Full headers field containing the text X-Spam-Flag: YES. Set the action to Quarantine message or Move to spam.

Alternatively, have Spam Killer modify the Subject header for messages above the threshold by appending [SPAM]. You can then create a standard Gmail filter: Subject contains "[SPAM]" with the action Skip Inbox, Apply label: Spam. This approach works in both individual Gmail accounts and Google Workspace, without requiring admin-level configuration.

3. Postfix: header_checks

If you run your own Postfix server as the upstream for Spam Killer, you can use Postfix's header_checks to act on X-Spam headers before the message reaches a user's mailbox. Add the following to /etc/postfix/main.cf:

header_checks = regexp:/etc/postfix/header_checks

Then create or edit /etc/postfix/header_checks:

# Discard very high-scoring spam (score > 8.0)
/^X-Spam-Score: [89]\.[0-9]+/ DISCARD

# Add warning tag for messages flagged as spam
/^X-Spam-Flag: YES/ PREPEND X-Postfix-Spam-Warning: Message flagged by upstream filter

Postfix header_checks actions include DISCARD (silently drop), REJECT (return a 5xx to the proxy — not recommended here since the proxy already accepted it), REDIRECT (forward to a different address), and PREPEND (add a header). Run postmap -fq - regexp:/etc/postfix/header_checks < /etc/postfix/header_checks to test syntax, then reload Postfix.

For delivery to specific spam folders, combine header_checks with a Procmail or Sieve rule at the delivery stage.

4. Thunderbird: Message Filters

Thunderbird supports message filters that can match on arbitrary headers. Go to Tools → Message Filters, click New, and set the filter to run on incoming messages. In the criteria section, choose Customize... from the first dropdown, then click Add to define a custom header. Enter X-Spam-Flag as the header name. Back in the filter, set the condition to X-Spam-Flag is YES.

Set the action to Move Message to → Junk or to a custom folder you have created for spam review. You can add a second filter rule for X-Spam-Score with a numeric comparison — Thunderbird supports "is greater than" comparisons for numeric headers when you define the header as a numeric type in the custom header dialog.

5. Apple Mail: Rules on Custom Headers

Apple Mail's rule interface is simpler but still sufficient for X-Spam header matching. Go to Mail → Settings → Rules → Add Rule. In the conditions section, change the dropdown from "From" to "Any header". Set the condition to Contains and enter the value X-Spam-Flag: YES.

Set the action to Move Message → Spam (or create a "Filtered Spam" mailbox and move there). Apple Mail evaluates rules on message download, so this will apply to all incoming mail automatically.

For score-based rules in Apple Mail, use "Any header" Contains "X-Spam-Status: Yes" as the match criterion — this catches all messages where the filter verdict was Yes regardless of the numeric score. Apple Mail does not support numeric comparisons in header rules, so granular score-based tiering is better implemented at the Postfix or Exchange level.

Tips for Handling False Positives

The most important rule when setting up spam folder routing is to use a folder, not immediate deletion, for at least the first few weeks. False positives — legitimate messages that score above the threshold — do happen, particularly for newsletters, automated notifications, and mail from small or new domains. If you delete them silently, you will not know they were missed.

Set up a weekly habit of scanning the spam folder for misclassified mail. When you find one, use the Spam Killer whitelist to add the sender's address or domain so future messages from them skip the score-based rules. After a month of tuning, the false positive rate should be low enough that you can comfortably raise the auto-delete threshold or reduce the review frequency.

Never set a delete rule at a score threshold below 0.80. Even well-tuned filters occasionally catch legitimate mail in the 0.50 to 0.80 range, and silent deletion is very difficult to debug after the fact.