SMTP & Email
Geekonomics uses SMTP to send password-reset emails. There are two configuration tiers, and the app picks whichever is available:
- Platform SMTP — set in
.envby the host operator. Used as the default for every tenant on the install. - Per-tenant SMTP — set in Settings → Email (SMTP) by a company admin. If present, it overrides the platform default for that tenant.
If neither is configured, the Forgot password? link is hidden on the sign-in page and password resets must be done manually by an admin in the Admin Console or the Platform panel.
Platform SMTP (host operator)
Set these five variables in .env. All five must be set for platform SMTP to be active:
| Variable | Example | Notes |
|---|---|---|
APP_URL | https://books.geekonomics-app.com | Base URL used in reset-link emails. No trailing slash. |
SMTP_HOST | smtp.example.com | Your SMTP provider hostname |
SMTP_PORT | 587 | Usually 587 (STARTTLS) or 465 (SSL) |
SMTP_USER | noreply@example.com | SMTP auth user |
SMTP_PASS | (your password) | SMTP auth password |
SMTP_FROM | "Geekonomics <noreply@example.com>" | The From header in outgoing email |
Restart the container after editing .env so the new values take effect.
Common providers
| Provider | Host | Port |
|---|---|---|
| Gmail | smtp.gmail.com | 587 (use an App Password) |
| SendGrid | smtp.sendgrid.net | 587 |
| Mailgun | smtp.mailgun.org | 587 |
| Postmark | smtp.postmarkapp.com | 587 |
| Amazon SES | email-smtp.us-east-1.amazonaws.com | 587 |
Per-tenant SMTP
A company admin can override the platform default — useful if you want password reset emails to come from your own domain.
- Sign in as an admin and go to Settings → Email (SMTP)
- The page shows whether platform SMTP is active
- Fill in your SMTP host, port, user, password, and From address
- Click Save
Testing the configuration
After saving, click Send Test Email. The app sends a single test message to your own email address (the email on your user account). Check your inbox to confirm delivery.
If the test fails, the error message is shown on the page — common causes:
- Wrong port (try 465 with SSL or 587 with STARTTLS)
- App-specific password required (Gmail, Outlook)
- DNS / firewall blocking outbound SMTP
- Sending domain not authorized (SES, SendGrid with strict sender verification)
Removing per-tenant SMTP
Click Remove SMTP Configuration. The tenant falls back to the platform SMTP if one is configured, or password resets become unavailable until you add one again.
What gets sent
Currently SMTP is used only for password reset emails. The email contains a one-time link that expires after one hour.
Future versions may add invoice email delivery and notification emails using the same SMTP configuration.