Grafana HTML Mail Relay (FastAPI)

Project Overview

This project solves a practical alerting gap: Grafana default emails were hard to scan quickly during incidents.

I built a local FastAPI relay that receives Grafana webhook alerts, validates a shared token, formats clean HTML + plain-text emails, and sends them through SMTP.

What Was Implemented

• Webhook endpoint with header token validation (X-Webhook-Token)
• Alert payload parsing and normalization
• HTML + plain-text email generation with Jinja2 templates
• Subject cleanup for clearer signal in inboxes
• Local health endpoint for quick checks
• systemd service for persistent runtime and restart control

Operational Value

• Faster alert readability for real triage workflows
• Better separation between alert detection and message formatting
• Stable delivery path: Grafana -> webhook relay -> SMTP -> mailbox
• Easier troubleshooting with service logs and deterministic health checks

Reliability Workflow

• Timestamped backup before code edits
• Python syntax validation before restart
• Controlled service restart and verification
• Post-change test via Grafana contact point and inbox validation