email-reports

name	email-reports
description	Configure and trigger weekly habit progress email reports via SMTP. Use when you need to set up email delivery, test SMTP settings, send the weekly report immediately, or preview the report content. Triggers include "send report", "email summary", "weekly digest", "SMTP setup", or "habit email".

email-reports

Configure and trigger weekly habit progress email reports from habit-tracker.

When to use

• Setting up SMTP credentials for email delivery
• Testing that email delivery works
• Triggering the weekly report immediately (without waiting for the scheduled time)
• Debugging email delivery problems
• Previewing what the report will contain

Configuration

Email reports require SMTP credentials. Configure via API or environment variables.

Via API (persisted to database)

curl -X PATCH http://localhost:3000/api/settings \
  -H "Content-Type: application/json" \
  -d '{
    "email_enabled": "1",
    "email_smtp_host": "smtp.gmail.com",
    "email_smtp_port": "587",
    "email_smtp_user": "[e-mail]",
    "email_smtp_pass": "your-app-password",
    "email_to": "[e-mail]",
    "email_report_day": "0",
    "email_report_hour": "8",
    "timezone": "America/Los_Angeles"
  }'

email_report_day: 0=Sunday, 1=Monday, ..., 6=Saturday

Via environment variables

SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_SECURE=0
SMTP_USER=[e-mail]
SMTP_PASS=your-app-password
REPORT_TO=[e-mail]
TIMEZONE=America/Los_Angeles

Environment variables take effect on server restart.

Send test email

curl -X POST http://localhost:3000/api/email/test
# Sends a minimal test message to the configured REPORT_TO address
# Response: { "sent": true } or { "error": "..." }

Trigger weekly report now

curl -X POST http://localhost:3000/api/email/report
# Sends the full weekly report immediately regardless of schedule
# Response: { "sent": true, "habits": 5, "weekRate": 0.86 }

Get current settings

curl http://localhost:3000/api/settings

Response includes all email settings (passwords are masked as ****).

Report schedule

The report is sent by a cron job that runs every hour. When the current hour matches email_report_hour and the current day matches email_report_day (in the configured timezone), the report is sent.

To prevent duplicates, the server records last_report_sent_at. If a report was already sent within the past hour, the cron job skips.

Report contents

The HTML email (inline CSS only, no external assets) contains:

• Week date range (Mon-Sun)
• Overall completion rate this week vs last week
• Per-habit breakdown: 7 dots showing each day, percentage
• "Best habit" callout (highest completion rate)
• "Room to improve" callout (lowest completion rate, below 80%)

Troubleshooting

"Connection refused" or "ECONNREFUSED"

SMTP host or port is wrong. Check SMTP_HOST and SMTP_PORT.

"Authentication failed"

For Gmail: use an App Password, not your account password. Generate at myaccount.google.com/apppasswords.

Report not arriving on schedule

Check that email_enabled is set to 1 in settings. Verify email_report_day and email_report_hour match your expected send time. Check that timezone is set correctly (e.g., America/New_York).

Use POST /api/email/report to send manually and confirm SMTP is working.

"No recipients defined"

email_to or REPORT_TO is not set. Configure a recipient address.