email-reports

# 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)

```bash
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": "you@gmail.com",
    "email_smtp_pass": "your-app-password",
    "email_to": "you@gmail.com",
    "email_report_day": "0",
    "email_report_hour": "8",
    "timezone": "America/Los_Angeles"
  }'
```

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

### Via environment variables

```bash
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_SECURE=0
SMTP_USER=you@gmail.com
SMTP_PASS=your-app-password
REPORT_TO=you@gmail.com
TIMEZONE=America/Los_Angeles
```

Environment variables take effect on server restart.

## Send test email

```bash
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

```bash
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

```bash
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.