Email / SMTP

Configures the SMTP server KPImailer sends every report and alert through, plus the retry behavior and debugging tools around delivery.

Permissions

Found in Settings → Email, an administrator-only area. The basic connection (host, port, security, from address) is set up once during first-run setup - this page covers the full settings, including the parts you’re more likely to revisit later.

Steps

1. Open Settings → Email.

   

2. Fill in the connection: SMTP host, Port, Security (StartTLS or similar), From address, From display name, and the Username / Password your mail provider requires.

3. Tune delivery behavior:

   • Max retries - how many times KPImailer retries a send that fails.
   • Retry delay (seconds) - how long it waits between retries.
   • Send offset (seconds) - a delay applied before sending, useful for spacing out a burst of emails.

4. Set Debug recipients - a comma-separated list of addresses Bcc’d on every report and alert KPImailer sends. Leave it on while you’re actively configuring or troubleshooting reports.

5. Use Send test email to confirm delivery end to end. A successful test is required before you can save and move on.

6. Select Save.

When to change this

• Switching mail providers or rotating SMTP credentials - update host, username, and password together, then re-test.
• Reports failing or arriving late - check Max retries and Retry delay first; a flaky mail server may need more retries with a longer delay.
• Large recipient bursts - a Send offset spaces out a cycle/burst report’s many individual emails, which can help with mail providers that rate-limit bursts of sends from one account.
• Investigating what a report actually sent - add yourself to Debug recipients temporarily rather than guessing from the recipient list alone.

Worked example

Reports occasionally fail to send during a provider’s brief maintenance windows. An administrator raises Max retries from 3 to 5 and Retry delay from 30 to 60 seconds, saves, and sends a Send test email to confirm the connection still works - now a short provider hiccup is absorbed by retries instead of failing the report outright.

What can go wrong

Caution

Until email is configured and tested, scheduled reports fail at send time even if everything else is set up correctly - this is the first place to check when a report isn’t arriving.

Caution

Leaving Debug recipients set after you’re done troubleshooting means that address keeps getting a blind copy of every single report and alert indefinitely - clear it once you’ve confirmed what you needed to.

A Password field showing placeholder text means the stored password is unchanged - leave it empty to keep the current credential, and only fill it in when you’re actually rotating the password.