Configure SMTP with Amazon SES

You can send Plane's emails through Amazon Simple Email Service (SES) by verifying the domain you send from, creating SES SMTP credentials, and entering them in Plane's /god-mode/. SES works for any team, sends to any recipient once your account leaves the sandbox, and keeps working when other providers retire password-based SMTP.

WARNING

SES SMTP credentials aren't your AWS console password or your secret access key. The SMTP user name is an IAM access key ID. The SMTP password is a separate value that SES derives from that key's secret access key for one Region. If you enter a secret access key as the Password, sign-in fails with 535 Authentication Credentials Invalid.

Before you start

• An AWS account with permission to use SES and create IAM users.
• A domain you control, with access to its DNS records. You can verify a single email address instead, but a verified domain gives better delivery.
• Instance admin access to Plane's /god-mode/.
• Outbound access from the Plane server to the SES SMTP endpoint of your Region on port 587.

Step 1: Pick an AWS Region

SES is a regional service. Your verified identities, your sandbox status, your sending limits and your SMTP credentials all belong to one Region and don't carry over to another.

Pick one Region, for example the one closest to your Plane server, and switch the AWS console to it before each of the steps below. The SMTP endpoint for that Region is:

email-smtp.<region>.amazonaws.com

For example, email-smtp.us-east-1.amazonaws.com or email-smtp.eu-west-1.amazonaws.com. The SES console shows the exact endpoint for your Region under SMTP settings.

Step 2: Verify the domain you send from

SES sends only from an address or domain you have verified. Verify the domain that your sender address uses, for example yourcompany.com for plane@yourcompany.com.

We recommend a subdomain used only for Plane's mail, for example plane.yourcompany.com. Its sending reputation stays apart from your company's own mail, and its DNS records stay apart from the SPF, DMARC and MX records your main domain already has. A verified domain covers its subdomains, but a verified subdomain doesn't cover its parent. If you verify plane.yourcompany.com, the sender address has to end in @plane.yourcompany.com.

1. Open the SES console and select Identities in the sidebar.
2. Select Create identity.
3. Choose Domain and enter your domain.
4. Keep Easy DKIM selected as the signing method, with a 2048-bit key.
5. Select Create identity.
6. SES shows three CNAME records. Add all three to your domain's DNS. If the domain is in Amazon Route 53 in the same account, SES can add them for you.

Add the records as plain CNAME records. Two DNS settings keep the identity stuck in Pending:

• Cloudflare proxy. Cloudflare sets new CNAME records to Proxied by default. A proxied record hides the CNAME from SES. Set all three records to DNS only.
• Duplicated domain. Some DNS providers add your domain to every record name. On those, enter only the part before your domain, for example abc123._domainkey. If you enter the full name, the record ends up at abc123._domainkey.yourcompany.com.yourcompany.com.

Verification usually completes within an hour of the DNS records going live, but it can take up to 72 hours. The identity status changes to Verified.

To finish setting up the domain:

• SPF. Easy DKIM is enough for SES to send. Add or update an SPF record that includes amazonses.com only if you also set up a custom MAIL FROM domain, because SES uses its own MAIL FROM domain by default.
• DMARC. If the domain has no DMARC record yet, add one, for example _dmarc.yourcompany.com with the value v=DMARC1; p=none;. If it already has one, keep it and don't add a second. Mailbox providers treat a domain with two DMARC records as if it had none. A subdomain follows its parent domain's DMARC record, so it usually needs no record of its own. Gmail and Yahoo require DMARC for bulk senders, and it helps every mailbox provider trust your mail.

With the default MAIL FROM domain, SPF checks amazonses.com, not your domain. Your mail passes DMARC because of the Easy DKIM signature.

TIP

To verify one address instead of a domain, choose Email address in step 3. SES sends a link to that address, and the identity is verified once someone opens it. Mail sent this way isn't signed with your own domain's DKIM key, so it can't pass DMARC. If the address's domain has a DMARC policy of p=quarantine or p=reject, mailbox providers put the mail in spam or reject it.

Step 3: Move out of the SES sandbox

Every new SES account starts in the sandbox in each Region. In the sandbox, SES:

• Sends only to verified email addresses and domains. Invites and notifications to anyone else fail.
• Sends at most 200 emails in 24 hours, and one email per second.

Plane emails people who aren't verified in SES, such as invited members, so request production access before you go live.

1. In the SES console, open Account dashboard.
2. Select Request production access.
3. Choose the Transactional mail type.
4. Enter your website URL, for example your Plane domain.
5. Optionally, add other contacts for AWS to email, and pick a contact language.
6. Accept the AWS Service Terms and Acceptable Use Policy, and submit the request.

AWS usually replies within 24 hours, in a support case. If AWS asks how you send email, explain that Plane sends sign-in codes, invitations and notifications only to members of your workspace, and that members can turn off notification emails. Until AWS approves the request, you can test Plane by sending to addresses you have verified. After approval, the account dashboard shows your new daily sending quota and maximum send rate. Review SES quotas to plan for larger workspaces.

Step 4: Create SMTP credentials

1. In the SES console, select SMTP settings in the sidebar.
2. Note the SMTP endpoint for your Region.
3. Select Create SMTP credentials. This opens IAM to create a user for SMTP.
4. Keep or change the user name, for example plane-ses-smtp, and select Create user.
5. Copy the SMTP user name and SMTP password, or download the .csv file.

WARNING

AWS shows the SMTP password only once. If you lose it, create new SMTP credentials. Treat the password as a secret.

SMTP credentials work only in the Region where you created them.

The IAM user that SES creates has a policy that allows ses:SendRawEmail from every verified identity in the account. Plane needs that action from your sending domain only. If other teams send through SES in the same AWS account, replace the policy with one that names your domain identity:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "ses:SendRawEmail",
      "Resource": "arn:aws:ses:<region>:<account-id>:identity/<your-domain>"
    }
  ]
}

TIP

If you manage IAM with Terraform, you can skip the console. Create an IAM user and an aws_iam_access_key for it. The key's id is the SMTP user name, and its ses_smtp_password_v4 attribute is the SMTP password for the provider's Region.

Step 5: Enter the settings in Plane

Open https://<your-plane-domain>/god-mode/, select Email in the sidebar, turn on Secure emails from your own instance if it is off, and enter these values.

Plane field	Value
Host	Your Region's SMTP endpoint, for example email-smtp.us-east-1.amazonaws.com
Port	587
Sender's email address	An address on your verified domain, for example plane@yourcompany.com
Email security	TLS
Username	The SMTP user name from Step 4
Password	The SMTP password from Step 4

Then:

1. Select Save changes.
2. Select Send test email, enter an address in Receiver email, and select Send email.
3. Confirm the test email arrives. Check the spam folder too.

To show a name with the address, enter the sender as Plane <plane@yourcompany.com>.

SES accepts these port and security combinations:

Port	Plane Email security
587 or 2587	TLS
465 or 2465	SSL
25	TLS

Use 587 unless your network blocks it. Amazon EC2 restricts outbound traffic on port 25 by default, so avoid it when Plane runs on AWS.

If the test reports success but a user still gets no email:

1. In the SES console, select Suppression list in the sidebar and look for the user's address. SES adds an address to this list after a hard bounce or a complaint. Later mail to that address is accepted and then dropped, and Plane shows no error. Remove the address once the cause is fixed.

2. Run this inside Plane's worker container. The worker sends sign-in codes, invitations and notifications, so the command tests the connection those emails use. It prints the error that SES returns.

   python manage.py test_email someone@yourcompany.com

Troubleshoot

When a test email fails, Plane shows a short reason but doesn't log the SMTP error. SES rejects an unverified sender or recipient after the message is sent, so Plane shows its general message for those. To see the exact error from SES, 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 or SMTP error	Likely cause	Fix
Invalid credentials provided / 535 Authentication Credentials Invalid	Wrong SMTP user name or password, a secret access key entered as the password, or credentials from another Region.	Create new SMTP credentials in the same Region as the Host (Step 4).
Could not send email. Please check your configuration and 554 Message rejected: Email address is not verified naming the sender	The sender's address or domain isn't verified in this Region.	Verify the domain (Step 2) in the same Region as the Host.
Could not send email. Please check your configuration and 554 Message rejected: Email address is not verified naming the recipient	The account is still in the sandbox, and the recipient isn't verified.	Request production access (Step 3).
Timeout error while trying to connect to the SMTP server., or the test keeps loading for minutes	A firewall, security group or hosting provider blocks the port.	Open outbound TCP 587 to the SES endpoint, or try 2587.
SMTP server disconnected unexpectedly., or the test keeps loading	Port 465 or 2465 with Email security set to TLS.	Use one of the combinations in Step 5.
Could not send email. Please check your configuration as soon as you send the test	Port 587 or 2587 with Email security set to SSL.	Use one of the combinations in Step 5.
454 Throttling failure: Maximum sending rate exceeded	Plane is sending faster than your SES send rate.	Request a higher sending quota in the SES console.
454 Throttling failure: Daily message quota exceeded	You reached the 24-hour sending quota.	Wait for the quota to free up, or request a higher quota.
Test email works, then mail stops	AWS paused sending because of high bounce or complaint rates.	Check Reputation metrics in the SES console and contact AWS.

Keep delivery healthy

• Watch Reputation metrics in the SES console. AWS places an account under review when its bounce rate reaches 5% or its complaint rate reaches 0.1%, and can pause sending at 10% bounces or 0.5% complaints.
• Set CloudWatch alarms so you hear about a problem before AWS acts on it. Alarm on Reputation.BounceRate and Reputation.ComplaintRate in the AWS/SES namespace below the review thresholds, for example at 0.04 and 0.0008.
• Alarm on the daily sending quota too. In the Service Quotas console, open Amazon SES, select Sending quota, and create a CloudWatch alarm at 80% of the quota. At 100%, SES rejects every email, sign-in codes included, until the 24-hour window moves on.
• Remove people who leave your organization from Plane, so notifications don't bounce.
• Rotate the SMTP credentials when people with access to them leave. An IAM user can have two access keys, so you don't need a new user. Create a second access key for the SMTP user, and convert its secret access key to an SMTP password. In /god-mode/, enter the new access key ID as the Username and the new SMTP password as the Password. Send a test email, then deactivate and delete the old access key.

References

• Configure SMTP for email notifications