hermes-skills/skills/email/email-workflows/references/bounce-check.md

Bounce-Back Email Detection

Script: /root/.hermes/scripts/bounce-check.py

What it does

Scans the INBOX for delivery-failure emails (Mailer-Daemon, Postmaster, "mail delivery failed" subjects) and reports them. Silent when no bounces found.

Detection logic

Signal	What it catches
Subject contains	mail delivery failed, undelivered, delivery status notification, returned mail, non-delivery, undeliverable, delivery report, returned to sender, message bounced
Sender contains	mailer-daemon, postmaster, mail delivery system
Body contains	permanent error, could not be delivered

Pitfalls

• Sender string matching must be exact. A sender like bounces@alerts.oknotify3.com (OkCupid) contains "bounces" in the local part, but the domain is a marketing platform — not a bounce. Only match known bounce-role senders (mailer-daemon, postmaster, mail delivery system).
• Email headers can be email.header.Header objects — calling .lower() on them raises AttributeError. Always convert via str(val) first.
• MIME multipart messages: The body check only examines text/plain parts. Bounces that are text/html only will not be caught by body content matching — subject/sender matching must catch them.

Setup

cronjob(action='create', name='bounce-check', schedule='every 1h',
  script='bounce-check.py', no_agent=True, deliver='origin')