Configure SMTP for email notifications
Plane sends email through an SMTP server that you configure in /god-mode/. Set it up during installation or later. Until you do, users can't receive sign-in codes, password reset links, invitations, notifications or exports by email.
INFO
Plane currently supports SMTP authentication only via email and password. OAuth-based SMTP configurations aren't supported.
What Plane sends by email
- Sign-in codes and password reset links.
- Workspace and project invitations.
- Notifications for work items, pages, intake, initiatives and teamspaces, when you're added to a project or subscribed to something, and when someone shares a page or view with you.
- Messages when your account's email changes or your account is activated.
- Analytics and page exports.
- Automation and recurring work item messages, and a notice when a webhook is turned off.
Configuration
- Open
https://<your-plane-domain>/god-mode/and select Email in the sidebar. - Turn on Secure emails from your own instance.
- Fill in the fields below.
- Select Save changes. Plane shows "Email Settings updated successfully".
- Send a test email.
| Field | Required | What to enter |
|---|---|---|
| Host | Yes | The address of your SMTP server, for example smtp.yourprovider.com. |
| Port | Yes | The port for outgoing email. Use 587 with TLS or 465 with SSL, unless your provider says otherwise. |
| Sender's email address | Yes | The address your users see on Plane's emails. Your provider has to allow sending from it, which usually means verifying it first. |
| Email security | No | TLS (STARTTLS, usually port 587), SSL (implicit TLS, usually port 465), or No email security. Choose the one your provider's port uses. |
| Username | No | The SMTP username. |
| Password | No | The SMTP password. |
Username and Password are under Authentication. They're optional, but we recommend setting them for your SMTP server. Most providers reject email without them.
Save changes stays off until every required field is filled in and you have changed something.
WARNING
Test your settings before you rely on them. Misconfigured settings can lead to email bounces and errors.
Send a test email
- On the Email screen, select Send test email.
- Enter an address in Receiver email.
- Select Send email.
If it works, Plane says it has sent the test email to that address. The email's subject is "Email Notification from Plane". Check the spam folder if you can't find it.
The test uses the settings that are saved, so select Save changes before you send it.
If the test reports success but users still get no email, run this inside Plane's worker container:
python manage.py test_email someone@yourcompany.comThe worker sends sign-in codes, invitations and notifications, so the command tests the connection those emails use. It prints the error your provider returns. Also check your provider's suppression or bounce list for the user's address. Providers such as Amazon SES and SendGrid accept mail to a suppressed address and then drop it.
Troubleshoot
When a test email fails, Plane shows one of these messages but doesn't log the SMTP error. To see the full error, run python manage.py test_email in the worker container. For emails that Plane sends to users, the error is in the worker container logs.
| Plane message | What to check |
|---|---|
| Invalid credentials provided | The Username and Password. Some providers need a separate SMTP password or an app password. |
| Could not connect with the SMTP server. | The Host and Port. |
| From address is invalid. | The Sender's email address. It must be verified with your provider or match the mailbox you sign in with. |
| All recipient addresses were refused. | The Receiver email, and whether your provider limits who you can send to. |
| SMTP server disconnected unexpectedly. | Email security matches the port, for example TLS with 587 or SSL with 465. |
| Timeout error while trying to connect to the SMTP server. | Your firewall or hosting provider allows outbound traffic to the SMTP server on that port. |
| Network connection error. Please check your internet connection. | The Plane server can reach the network and resolve the Host. |
| Invalid email header. | The Sender's email address has no line breaks or extra characters. |
| Could not send email. Please check your configuration | Any other error. Run python manage.py test_email in the worker container to see the SMTP error from your provider. |
Turn off email
Turn off Secure emails from your own instance on the Email screen. Plane shows "Email feature disabled".
WARNING
Turning off email clears every saved email setting, including the username and password. To turn it back on, enter the settings again.
Configuration for popular email service providers
| Provider | Guide |
|---|---|
| Amazon SES | Configure SMTP with Amazon SES |
| Microsoft 365 (Outlook) | Configure SMTP with Microsoft 365 (Outlook) |
Other SMTP providers, such as SendGrid, Mailgun, Postmark and Google Workspace, work the same way. Get the host, port, security setting and SMTP credentials from your provider, and enter them on the Email screen.
TIP
Google Workspaces
If your Plane instance is not accessible on the internet, Gmail may block profile photos or other embedded images in email notifications. This occurs because Gmail uses Google's secure image proxy to serve images for security purposes.
To resolve this issue, you must configure the Image URL proxy allowlist in your Google Workspace settings to include your Plane instance's URL. Refer to Google's documentation for instructions: Allowlist image URLs.