Appearance
SMTP
Truetask uses SMTP to send transactional emails. Without SMTP configured, users cannot receive password resets, invitations, or email notifications.
What uses email
- Password resets — users who forget their password
- User invitations — inviting new team members
- Notifications — card assignments, mentions, and comments (if enabled)
- Email verification — confirming new email addresses
Configuration
SMTP can be configured in three ways:
- Settings > Server > SMTP from within the application (recommended — no restart required)
- During the setup wizard on first install
- In the
.envfile (requires a restart)
Settings UI
| Field | Description |
|---|---|
| Enable SMTP | Toggle to turn email sending on or off |
| Mail Server Host | SMTP server hostname (e.g., smtp.mailgun.org) |
| Port | SMTP port. Use 587 for STARTTLS, 465 for SSL |
| Username | SMTP authentication username |
| Password | SMTP authentication password |
| TLS Encryption | Auto (StartTLS), Always, or None |
| Authentication Method | PLAIN (default) or LOGIN |
| Local Name | Domain name for the EHLO/HELO command (default: localhost) |
Use the Test Connection section at the bottom to send a test email and verify your configuration before saving.
Environment variables
The same settings can be configured in the .env file (requires a restart):
| Variable | Default | Description |
|---|---|---|
POCKETBASE_SMTP_HOST | — | Mail server host |
POCKETBASE_SMTP_PORT | 587 | Port |
POCKETBASE_SMTP_USERNAME | — | Username |
POCKETBASE_SMTP_PASSWORD | — | Password |
POCKETBASE_SMTP_SENDER_NAME | Truetask | Display name on outgoing emails |
POCKETBASE_SMTP_SENDER_ADDRESS | — | From address (e.g., [email protected]) |
Example .env configuration
env
POCKETBASE_SMTP_HOST=smtp.mailgun.org
POCKETBASE_SMTP_PORT=587
[email protected]
POCKETBASE_SMTP_PASSWORD=your-smtp-password
POCKETBASE_SMTP_SENDER_NAME=Truetask
[email protected]Restart required for .env changes
Changes made in the .env file only take effect after restarting the services: ./truetask-start.sh. This is why configuring SMTP through the Settings UI is recommended — changes apply immediately and you can test right away.
Testing
After configuring SMTP (via UI or .env), verify it works:
- Go to Settings > Server > SMTP
- Enter a test email address in the Test Connection section
- Click Send Test Email
If the test email arrives, SMTP is configured correctly.
Common providers
| Provider | Host | Port | Notes |
|---|---|---|---|
| Mailgun | smtp.mailgun.org | 587 | Requires domain verification |
| SendGrid | smtp.sendgrid.net | 587 | Username is always apikey |
| Amazon SES | email-smtp.{region}.amazonaws.com | 587 | Requires IAM SMTP credentials |
| Postmark | smtp.postmarkapp.com | 587 | Server API token as password |
| Google Workspace | smtp.gmail.com | 587 | Requires App Password |
| Microsoft 365 | smtp.office365.com | 587 | Requires App Password or OAuth |
Recommendations
- Use a transactional email service (Mailgun, SendGrid, Postmark) rather than a personal email account. They handle deliverability, bounce management, and rate limits.
- Set the sender address to your domain (e.g.,
[email protected]) to avoid spam filters. - Enable settings encryption during setup to protect SMTP credentials stored in the database.
Troubleshooting
Emails not arriving
- Check spam/junk folders
- Verify the sender address domain has correct SPF and DKIM records
- Test with the built-in test email feature in Settings > Server > SMTP
Authentication failed
- Verify username and password are correct
- Some providers (Google, Microsoft) require App Passwords instead of account passwords
- Check that the SMTP port matches your provider's requirements