solar/umami-smtp-and-testing.md

Umami SMTP configuration and testing

This project uses a self-hosted Umami instance for analytics. To ensure reliable email delivery (invites, password resets, reports), configure SMTP on the Umami server and verify deliverability.

1. Decide on SMTP provider

Use a provider with good deliverability, for example:

• Postmark
• Mailgun
• SendGrid
• Amazon SES

You will need:

• SMTP host and port
• Username and password (or API key)
• Recommended encryption mode (TLS/STARTTLS)
• Allowed from address and domain (e.g. analytics@degelas.be)

2. Add SMTP environment variables for Umami

Extend your server-side environment (e.g. in umami.env) with SMTP settings. Exact variable names depend on your Umami version; consult the Umami docs for the version you deploy. A typical configuration looks like:

UMAMI_SMTP_HOST=smtp.yourprovider.com
UMAMI_SMTP_PORT=587
UMAMI_SMTP_USERNAME=analytics@degelas.be
UMAMI_SMTP_PASSWORD=change_me_to_provider_password_or_api_key
UMAMI_SMTP_SECURE=false        # true for port 465, false for STARTTLS on 587
UMAMI_EMAIL_FROM="Solar Analytics <analytics@degelas.be>"

Then wire these into the umami service in umami-docker-compose.yml on the server:

  umami:
    # ...
    environment:
      DATABASE_URL: postgresql://${UMAMI_DB_USER:-umami}:${UMAMI_DB_PASSWORD}@umami-db:5432/${UMAMI_DB_NAME:-umami}
      APP_SECRET: ${UMAMI_APP_SECRET}
      DISABLE_TELEMETRY: "true"
      UMAMI_WEBSITE_URL: ${UMAMI_WEBSITE_URL:-https://analytics.example.com}
      UMAMI_SMTP_HOST: ${UMAMI_SMTP_HOST}
      UMAMI_SMTP_PORT: ${UMAMI_SMTP_PORT}
      UMAMI_SMTP_USERNAME: ${UMAMI_SMTP_USERNAME}
      UMAMI_SMTP_PASSWORD: ${UMAMI_SMTP_PASSWORD}
      UMAMI_SMTP_SECURE: ${UMAMI_SMTP_SECURE:-false}
      UMAMI_EMAIL_FROM: ${UMAMI_EMAIL_FROM}

Note: Keep the real credentials in a private umami.env file on the server (not committed to source control).

3. DNS and deliverability

For the sending domain (e.g. degelas.be):

1. Configure SPF to include your SMTP provider.
2. Configure DKIM using DNS records provided by your SMTP provider.
3. Optionally configure DMARC in monitor or reject mode.

This significantly improves the chance that Umami emails land in the inbox instead of spam.

4. Test Umami email flows

After deploying the updated configuration:

1. Log into the Umami dashboard as admin.
2. Invite a test user account (e.g. a Gmail address and a work address).
3. Trigger a password reset for that account.
4. Verify that:
   • Both emails arrive.
   • The from address and subject look correct.
   • The email headers show SPF/DKIM/DMARC passing.

If you use any Umami report scheduling features that send emails, configure and test at least one scheduled report as well.

5. Validate geo stats

Once Umami is running with GeoIP configured:

1. Use a VPN to simulate visits from different countries (e.g. Belgium, Netherlands, Germany, US).
2. Load the main app page and some key views (dashboard, prices, trading, log).
3. In the Umami dashboard, open the site corresponding to degelas.be and:
   • Check that page views and events increase.
   • Confirm that country (and, if enabled, region/city) statistics appear under the appropriate reports.

6. Observability

• Monitor Umami logs (container logs) for SMTP failures.
• If your SMTP provider exposes dashboards or webhooks for bounces/complaints, enable them and periodically review issues.