qq-notify

A tiny, dependency-free email notification helper for scripts, cron jobs, and long-running task watchers. SMTP credentials live in one config file, so changing the password or recipient is a one-line edit instead of hunting through every script.

Originally built to email status updates from remote GPU training jobs (where China-region delivery to Gmail is slow/unreliable, so a self-to-self QQ Mail loop is used), but it works with any SMTP-over-SSL provider.

Features

• Zero dependencies — Python standard library only (smtplib, ssl, email).
• Two ways to call — import as a module, or pipe to it from the shell / cron.
• Centralized config — one notify_config.json; falls back to environment variables.
• Automatic retries — 3 attempts with backoff, to survive flaky SMTP servers.
• Attachments — attach files (logs, plots, checkpoints).
• Multiple recipients — comma-separated.

Setup

cp notify_config.example.json notify_config.json
# edit notify_config.json: fill in your SMTP user and app password (authorization code)

notify_config.json is gitignored so your password never gets committed. If the file is absent, the tool reads NOTIFY_SMTP_USER / NOTIFY_SMTP_PASS / NOTIFY_TO from the environment instead.

Config fields

Field	Default	Notes
smtp_host	smtp.qq.com	Any SMTP-over-SSL host
smtp_port	465	SSL port
smtp_user	—	Sender address / login
smtp_pass	—	App password / authorization code (not your login password)
to	—	Recipient(s), comma-separated

Usage

Python

from notify import send

send("Training done", "Best PSNR 34.1 dB")
send("With attachment", body, attachments=["curve.png"])

ok = send(subject, body)   # returns True/False; already retried on failure

Command line / pipe

python3 notify.py "Subject" "Body"
echo "Body" | python3 notify.py "Subject"
tail -20 train.log | python3 notify.py "Training progress"

Exit code 0 on success, 1 on failure (after retries). Errors go to stderr; no traceback is raised.

Getting an SMTP app password

Most providers require an app-specific password rather than your account password:

• QQ Mail: Settings → Account → enable IMAP/SMTP → generate authorization code.
• Gmail: enable 2FA → create an App Password.
• Outlook / others: see your provider's SMTP / app-password docs.

License

MIT