alpinebits_python/docs/EMAIL_MONITORING_QUICKSTART.md

Email Monitoring Quick Start

Get email notifications for errors and daily reports in 5 minutes.

1. Configure SMTP Settings

Edit config/config.yaml and add:

email:
  smtp:
    host: "smtp.gmail.com"
    port: 587
    username: !secret EMAIL_USERNAME
    password: !secret EMAIL_PASSWORD
    use_tls: true
  from_address: "noreply@yourdomain.com"
  from_name: "AlpineBits Monitor"

2. Set Environment Variables

Create a .env file in the project root:

EMAIL_USERNAME=your-email@gmail.com
EMAIL_PASSWORD=your-app-password

Note: For Gmail, use an App Password, not your regular password.

3. Enable Error Alerts

In config/config.yaml:

email:
  monitoring:
    error_alerts:
      enabled: true
      recipients:
        - "alerts@yourdomain.com"
      error_threshold: 5
      buffer_minutes: 15
      cooldown_minutes: 15

How it works:

• Sends immediate alert after 5 errors
• Otherwise sends after 15 minutes
• Waits 15 minutes between alerts (cooldown)

4. Enable Daily Reports (Optional)

In config/config.yaml:

email:
  monitoring:
    daily_report:
      enabled: true
      recipients:
        - "admin@yourdomain.com"
      send_time: "08:00"
      include_stats: true
      include_errors: true

5. Test Your Configuration

Run the test script:

uv run python examples/test_email_monitoring.py

This will:

• ✅ Send a test email
• ✅ Trigger an error alert
• ✅ Send a test daily report

What You Get

Error Alert Email

When errors occur, you'll receive:

🚨 AlpineBits Error Alert: 5 errors (threshold exceeded)

Error Count: 5
Time Range: 14:25:00 to 14:30:00

Errors:
----------------------------------------------------------------------
[2025-10-15 14:25:12] ERROR: Database connection timeout
  Module: db:245

[2025-10-15 14:26:34] ERROR: Failed to process reservation
  Module: api:567
  Exception: ValueError: Invalid hotel code

Daily Report Email

Every day at 8 AM, you'll receive:

📊 AlpineBits Daily Report - 2025-10-15

Statistics:
  total_reservations: 42
  new_customers: 15
  active_hotels: 4

Errors (3):
  [08:15:23] ERROR: Connection timeout
  [12:45:10] ERROR: Invalid form data
  [18:30:00] CRITICAL: Database unavailable

Troubleshooting

No emails received?

1. Check your SMTP credentials:

   echo $EMAIL_USERNAME
   echo $EMAIL_PASSWORD
   

2. Check application logs for errors:

   tail -f alpinebits.log | grep -i email
   

3. Test SMTP connection manually:

   uv run python -c "
   import smtplib
   with smtplib.SMTP('smtp.gmail.com', 587) as smtp:
       smtp.starttls()
       smtp.login('$EMAIL_USERNAME', '$EMAIL_PASSWORD')
       print('✅ SMTP connection successful')
   "
   

Gmail authentication failed?

• Enable 2-factor authentication on your Google account
• Generate an App Password at https://myaccount.google.com/apppasswords
• Use the App Password (not your regular password)

Too many emails?

• Increase error_threshold to only alert on serious issues
• Increase buffer_minutes to batch more errors together
• Increase cooldown_minutes to reduce alert frequency

Next Steps

• Read the full Email Monitoring Documentation
• Configure custom statistics for daily reports
• Set up multiple recipient groups
• Integrate with Slack or PagerDuty (coming soon)

Support

For issues or questions:

• Check the documentation
• Review test examples
• Open an issue on GitHub