# 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

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