Email Forwarding Checker

A small programm that periodically checks if a configured email forwarding for different addresses is working by sending test emails. Purpose is that you will get a notification via MQTT if forwarding stops working and it does not go unnoticed.

How it works

Configure a list of email addresses that should be checked. For those addresses there should be a forwarding configured. Then test emails will be sent periodically to those email adresses via a configurable SMTP server.

Lastly, it will be checked if the test emails arrived at the destination by looking into a configurable IMAP postbox. If the test emails do not arrive there within a specific amount of time, then the forwarding is considered to be not working.

Hot to use it

Install the Python package via pip, install it from source or use the docker image:

docker pull ghcr.io/verybadsoldier/email_forwarding_checker

Docker

Example docker-compose.yml:

version: '3'
services:
  email_forwarding_checker:
    image: ghcr.io/verybadsoldier/email_forwarding_checker:0.2.2
    container_name: email_forwarding_checker
    volumes:
      - ./config.yml:/config.yml
    restart: always
    environment:
      - TZ=Europe/Berlin

Configuration

Example config:

smtp:
  host: smtp.zoho.com
  username: myuser
  password: mypasswd
  sender: checker@check.com

imap:
  host: imap.zoho.com
  username: myimapuser
  password: myimappw

mqtt:
  host: 192.168.2.33
  topic_base: home/email_forwarding_checker

daemon:
  check_interval_hours: 1
  run_now: true  # run once instantly upon startup, then every check_interval_hours hours

email_timeout: 2400  # if the test email does not arrive with this time in seconds, then the forwarding is considered to have failed
repeat_interval: 5  # within email_timeout, check every n seconds for the test email
delete_emails: false  # delete the test emails from the IMAP postbox after arrival
emails:
        - address1@gmail.com
        - address2@gmail.com:3  # optionally suffix :<n> to retry up to n times before marking as failed
        - address3@gmail.com

Healthchecks.io integration

The checker can ping healthchecks.io (or a self-hosted Healthchecks instance) for each monitored address. A start ping is sent before each check and a success or fail ping is sent once the result is known, giving you dead-man's-switch monitoring.

Add the following section to your config:

healthchecks:
  enabled: true
  # Ping URL template. Use {slug} as a placeholder for the per-address slug.
  # For healthchecks.io use: https://hc-ping.com/{slug}
  # For a self-hosted instance use e.g.: https://hc.example.com/ping/<project-token>/{slug}
  url_template: https://hc-ping.com/{slug}
  # Optional prefix prepended to the generated slug for each address.
  # The slug is: slug_prefix + email address with @ and . stripped.
  # Example: prefix "email-fwd-" + "user@example.com" -> "email-fwduserexamplecom"
  slug_prefix: "email-fwd-"

Create one check per monitored address in healthchecks.io, naming the slug to match the pattern above (slug_prefix + address with @ and . removed). Set the check period to slightly above daemon.check_interval_minutes so you get alerted when a run is missed entirely.