Skip to content

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 .env file (requires a restart)

Settings UI ​

FieldDescription
Enable SMTPToggle to turn email sending on or off
Mail Server HostSMTP server hostname (e.g., smtp.mailgun.org)
PortSMTP port. Use 587 for STARTTLS, 465 for SSL
UsernameSMTP authentication username
PasswordSMTP authentication password
TLS EncryptionAuto (StartTLS), Always, or None
Authentication MethodPLAIN (default) or LOGIN
Local NameDomain 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):

VariableDefaultDescription
POCKETBASE_SMTP_HOST—Mail server host
POCKETBASE_SMTP_PORT587Port
POCKETBASE_SMTP_USERNAME—Username
POCKETBASE_SMTP_PASSWORD—Password
POCKETBASE_SMTP_SENDER_NAMETruetaskDisplay 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:

  1. Go to Settings > Server > SMTP
  2. Enter a test email address in the Test Connection section
  3. Click Send Test Email

If the test email arrives, SMTP is configured correctly.

Common providers ​

ProviderHostPortNotes
Mailgunsmtp.mailgun.org587Requires domain verification
SendGridsmtp.sendgrid.net587Username is always apikey
Amazon SESemail-smtp.{region}.amazonaws.com587Requires IAM SMTP credentials
Postmarksmtp.postmarkapp.com587Server API token as password
Google Workspacesmtp.gmail.com587Requires App Password
Microsoft 365smtp.office365.com587Requires 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