Rewrite Microsoft's bounce messages before your users ever see them

Register the milter in main.cf

Alongside any milters you already run — order matters only if you have several, so keep content-modifying milters after any that just accept/reject. The last line, internal_mail_filter_classes = bounce, is the one people miss — without it the milter never sees a single bounce, because by default Postfix doesn't run its own locally-generated mail (bounces, in particular) through non_smtpd_milters at all; this setting opts that class of internal mail back into content filtering, and its default is empty:

smtpd_milters = inet:127.0.0.1:9900
non_smtpd_milters = inet:127.0.0.1:9900
milter_default_action = accept
internal_mail_filter_classes = bounce

Install pymilter and its build dependencies

pymilter compiles a small C extension against Sendmail's libmilter headers, so the -dev packages need to be present before pip can build it:

apt-get install -y libmilter-dev python3-dev
pip install pymilter

The milter itself

This version collects the body correctly, never lets an exception escape to eom() as an unintended TEMPFAIL, and requires the Microsoft host match plus one corroborating signal rather than any-3-of-4 (which rewrote non-Microsoft bounces too, since a null sender, multipart/report and Postfix's default subject are true of every Postfix bounce). Test it against your own mail flow before trusting it on live mailboxes:

#!/usr/bin/env python3
# microsoft-bounce-rewriter.py - Postfix milter on 127.0.0.1:9900
# Requires: pip install pymilter
import re, sys, html, traceback, email, email.policy
from email.mime.multipart import MIMEMultipart
from email.mime.text import MIMEText
import Milter

MICROSOFT_HOST = re.compile(r"\b[\w.-]*\.(protection\.outlook|outlook|hotmail)\.com\b", re.I)
MICROSOFT_DIAG = re.compile(r"\b(5\.7\.606|5\.1\.10|4\.4\.7)\b|access denied, banned sender|recipient address rejected", re.I)
DSN_SUBJECT = re.compile(r"^(undeliverable:|message not delivered|delivery has failed|undelivered mail returned to sender)", re.I)

# ---- Notice wording (edit here; both versions are built from these) ----
NOTICE_HEADING = "Your message was blocked by Microsoft - it was not delivered"
NOTICE_BODY = (
    "You sent this message to a Microsoft-hosted address (hotmail.com, "
    "outlook.com, live.com or msn.com). Microsoft's mail servers block "
    "legitimate senders unpredictably, and their original wording below "
    "is often unhelpful.")
NOTICE_LINKS = [
    ("Why this happens", "https://dumpmicrosoft.com"),
    ("A more reliable option for the recipient", "https://dumpmicrosoft.com/users.html"),
]

# Plain-text version: a boxed banner for clients that only show text.
_RULE = "=" * 70
REPLACEMENT_TEXT = (
    f"{_RULE}\n"
    f"  *** {NOTICE_HEADING.upper()} ***\n"
    f"{_RULE}\n\n"
    f"{NOTICE_BODY}\n\n"
    + "".join(f"  > {label}:\n    {url}\n" for label, url in NOTICE_LINKS)
    + f"\n{_RULE}\n"
    "  Original delivery failure notice follows\n"
    f"{_RULE}\n\n")


def build_html(original_text):
    # Inline styles only - most mail clients strip <style> blocks. Colours
    # are set explicitly for both background and text so dark-mode clients
    # that invert colours keep enough contrast.
    links = "".join(
        f'<p style="margin:6px 0;"><a href="{html.escape(url)}" '
        f'style="color:#9a3412;font-weight:bold;">{html.escape(label)} &rarr;</a></p>'
        for label, url in NOTICE_LINKS)
    return (
        '<!DOCTYPE html><html><body style="margin:0;padding:16px;'
        'font-family:Segoe UI,Arial,sans-serif;background:#ffffff;color:#1f2937;">'
        '<table role="presentation" width="100%" cellpadding="0" cellspacing="0" '
        'style="max-width:680px;border:3px solid #dc2626;border-radius:8px;'
        'background:#fef2f2;border-collapse:separate;">'
        '<tr><td style="background:#dc2626;color:#ffffff;padding:12px 16px;'
        'font-size:18px;font-weight:bold;">&#9888; '
        f'{html.escape(NOTICE_HEADING)}</td></tr>'
        '<tr><td style="padding:14px 16px;font-size:15px;line-height:1.5;color:#1f2937;">'
        f'<p style="margin:0 0 10px 0;">{html.escape(NOTICE_BODY)}</p>{links}'
        '</td></tr></table>'
        '<p style="margin:20px 0 6px 0;font-size:13px;color:#6b7280;">'
        'Original delivery failure notice:</p>'
        '<pre style="margin:0;padding:12px;background:#f3f4f6;color:#374151;'
        'font-size:12px;white-space:pre-wrap;border-radius:6px;">'
        f'{html.escape(original_text)}</pre>'
        '</body></html>')


def log(msg):
    print(msg, file=sys.stderr, flush=True)   # ends up in journalctl under systemd


class BounceRewriter(Milter.Base):
    def __init__(self):
        self._reset()

    def _reset(self):
        self.hdrs = []
        self.chunks = []
        self.is_dsn_envelope = False

    def envfrom(self, mailfrom, *args):
        self._reset()
        # DSNs use a null return-path (RFC 3464). pymilter passes it as '<>'.
        self.is_dsn_envelope = mailfrom in ("<>", "")
        return Milter.CONTINUE

    def header(self, name, value):
        self.hdrs.append((name, value))
        return Milter.CONTINUE

    def body(self, chunk):
        # FIX: the original never collected the body (and getbody() doesn't exist).
        self.chunks.append(chunk)
        return Milter.CONTINUE

    def eom(self):
        # FIX: never let an exception reach pymilter - it turns that into a
        # TEMPFAIL for the sender, which milter_default_action does NOT cover.
        try:
            self._rewrite()
        except Exception:
            log("microsoft-bounce-rewriter: error, message passed unchanged\n" + traceback.format_exc())
        return Milter.ACCEPT

    def _rewrite(self):
        headers = {k.lower(): v for k, v in self.hdrs}
        is_report = headers.get("content-type", "").lower().lstrip().startswith("multipart/report")

        # Cheap early exit: ordinary mail is never parsed or touched.
        if not (self.is_dsn_envelope and is_report):
            return

        # FIX: parse headers + body together, otherwise the MIME structure
        # (boundary lives in the Content-Type header) is invisible.
        head = b"".join(f"{k}: {v}\r\n".encode("utf-8", "surrogateescape") for k, v in self.hdrs)
        body = b"".join(self.chunks)
        msg = email.message_from_bytes(head + b"\r\n" + body, policy=email.policy.compat32)

        # FIX: message/delivery-status parses as a list of header blocks, so
        # get_payload(decode=True) returns None. Stringify the blocks instead.
        delivery_status = ""
        for part in msg.walk():
            if part.get_content_type() == "message/delivery-status":
                payload = part.get_payload()
                if isinstance(payload, list):
                    delivery_status = "\n".join(str(p) for p in payload)
                else:
                    delivery_status = str(payload)
                break

        subject = headers.get("subject", "")
        # FIX: null sender + multipart/report + Postfix's default subject are
        # true for EVERY Postfix bounce, so the original 3-of-4 score rewrote
        # non-Microsoft bounces too. Require the Microsoft host explicitly,
        # plus one corroborating signal.
        host_hit = bool(MICROSOFT_HOST.search(delivery_status))
        other_hit = bool(MICROSOFT_DIAG.search(delivery_status) or DSN_SUBJECT.search(subject))
        if not (host_hit and other_hit):
            log(f"microsoft-bounce-rewriter: DSN not matched (host={host_hit}, other={other_hit}), subject={subject!r}")
            return

        # The human-readable part is the FIRST child of multipart/report
        # (RFC 3464). Replace it with multipart/alternative holding a
        # bannered text/plain and a styled text/html version - RFC 3464
        # allows any content type for that first part, so the
        # delivery-status and original-message parts stay untouched.
        parts = msg.get_payload()
        if not isinstance(parts, list) or not parts or parts[0].get_content_type() != "text/plain":
            log(f"microsoft-bounce-rewriter: matched but first part isn't text/plain, left unchanged, subject={subject!r}")
            return
        first = parts[0]
        raw = first.get_payload(decode=True) or b""
        original = raw.decode(first.get_content_charset() or "utf-8", errors="replace")

        alt = MIMEMultipart("alternative")
        del alt["MIME-Version"]   # only belongs on the top-level message
        for sub in (MIMEText(REPLACEMENT_TEXT + original, "plain", "utf-8"),
                    MIMEText(build_html(original), "html", "utf-8")):
            del sub["MIME-Version"]
            alt.attach(sub)
        parts[0] = alt

        # FIX: replacebody() wants the BODY only - the original passed the
        # whole message, which would have pasted the headers into the body.
        out = msg.as_bytes(policy=email.policy.SMTP)
        new_body = out.split(b"\r\n\r\n", 1)[1]
        self.replacebody(new_body)
        log(f"microsoft-bounce-rewriter: rewrote DSN, subject={subject!r}")


if __name__ == "__main__":
    Milter.factory = BounceRewriter
    # FIX: body changes must be negotiated with the MTA up front, or
    # replacebody() raises.
    Milter.set_flags(Milter.CHGBODY)
    Milter.runmilter("microsoft-bounce-rewriter", "inet:9900@127.0.0.1", 240)

Give it a dedicated system account

Not root, not postfix — it only needs to bind a local port and read message content, not touch the mail queue directly:

useradd --system --no-create-home --shell /usr/sbin/nologin milter
install -o milter -g milter -m 0750 microsoft-bounce-rewriter.py /usr/local/bin/microsoft-bounce-rewriter.py

--system skips a login shell and home directory — there's nothing to clean up later. install copies the script and sets its ownership/mode in one command; 0750 keeps it readable and executable by milter alone, not world-readable, since it embeds your matching logic. Run both as root (or sudo) — the milter account itself never needs permission to create its own script or user.

Run it under systemd, then enable and verify

Pinned to that account with User=/Group=, so it starts on boot, restarts if it crashes, and is already listening on 127.0.0.1:9900 before Postfix tries to reach it — /etc/systemd/system/microsoft-bounce-rewriter.service:

[Unit]
Description=Microsoft bounce-rewriting milter for Postfix
After=network.target
Before=postfix.service

[Service]
ExecStart=/usr/bin/python3 /usr/local/bin/microsoft-bounce-rewriter.py
Restart=on-failure
RestartSec=2
User=milter
Group=milter

[Install]
WantedBy=multi-user.target

systemctl daemon-reload
systemctl enable --now microsoft-bounce-rewriter
ss -ltnp | grep 9900        # confirm it's listening before reloading Postfix
postfix reload

• milter_default_action = accept (step 1) means a milter outage fails open rather than blocking all mail server-wide — this filter should only ever add clarity, never become a new reason mail doesn't get delivered.
• Before=postfix.service only affects boot order. If you edit and restart the milter later, restart it on its own — Postfix keeps retrying the connection per milter_connect_timeout and doesn't need a restart itself.
• Watch journalctl -u microsoft-bounce-rewriter for the rewrote DSN/DSN not matched lines from step 1, and Postfix's own mail log for warning: milter lines if messages stop being rewritten.
• replacebody() replaces the whole body Postfix queues for delivery — which is why matching conservatively (the host-plus-corroborating-signal check in the script) matters so much more here than on the accept/reject pages elsewhere in this guide.