Email

1. Overview

Depotex sends email for password resets, invitations to new users and test messages. Set it up under Settings → Application → Email (super admins: the email:manage permission). Until email is on, Forgot password? isn't shown on the sign-in page and new users can't be invited by email.

Every provider below is reached over SMTP, the standard mail protocol: choose a preset and Depotex fills in the server, port and security for you. Amazon SES can also be used through its API with an IAM role instead of SMTP credentials (see Amazon SES with an IAM role). Available on every license tier.

Messages are first stored in the database and then sent in the background (every 10 seconds, by the mail-dispatch scheduled job). If the mail server is down, Depotex retries after 1, 5 and 15 minutes, 1 hour and 3 hours, then gives up. Messages the server refuses for good (for example an unknown recipient) aren't retried. In a cluster, each message is sent by one server. Once a message is sent or given up on, its content is deleted (it may contain a one-time link); only the recipient, type and status are kept, for 30 days.

2. Before you start

• An account with your provider that may send from the address you want to use (the from address), usually after verifying the address or domain with the provider.
• SMTP credentials for that account (see your provider below).
• Outbound access from every Depotex server to the provider's SMTP port (587, or 465 for TLS, or 25 for a local relay). Amazon SES through its API uses HTTPS (port 443) instead.
• The address people open Depotex at, for example https://depotex.example.com. Links in emails start with it.

3. Setting up email

At the top of the page, Delivery shows whether email is on and how it goes out, how many messages are waiting, and how many were sent or failed in the last 24 hours, with the last problem when there was one. Beside the form, Send a test email tries the settings on the screen and What recipients see shows the sender, reply-to address, server and links a message will have.

Screenshot needed

email-settings.png

Settings → Application → Email: delivery status, provider, server and security, with the test email and recipient preview beside them

1. Open Settings → Application → Email —
2. Choose a provider — Open the Provider list and pick your provider (your own SMTP server or relay, or an email service). Host, port and security are filled in; check them against your provider's instructions. Choosing a security option moves a standard port with it (587 for STARTTLS, 465 for TLS, 25 for None); a custom port stays.
3. Enter the credentials — Username and password (or API key) from your provider; see the table below for what each provider expects. The password is stored encrypted and never shown again; leave it empty later to keep it.
4. Enter the sender — From address (must be allowed to send at your provider), From name (shown as the sender, for example Depotex) and, optionally, a Reply-to address.
5. Enter the Depotex address — The full address people use to open Depotex, for example https://depotex.example.com. Depotex never takes it from the incoming request, so a forged request can't put someone else's site into a reset link. It's the same setting as Settings → General → Depotex address, also used by single sign-on.
6. Turn it on — Turn on Send email at the top of the page and select Save in the bar that appears at the bottom. If a field can't be saved, it is marked in red with the reason under it.
7. Send a test email — Under Send a test email, enter an address (yours by default) and select Send test email. It's sent right away with the settings on the screen, even before you save them, and tells you exactly what failed if it doesn't work.

4. Providers

5. Amazon SES with an IAM role

SES's SMTP interface only accepts SMTP credentials, which belong to an IAM user. To use an IAM role instead (an EC2 instance profile, an EKS or ECS task role, or a role in another account), choose Amazon SES and, under Sign in with, AWS credentials (IAM role). Depotex then sends through the SES API over HTTPS, and no SMTP password is stored.

Screenshot needed

email-ses-api.png

Settings → Application → Email: Amazon SES signing in with AWS credentials, with a region and a role to assume

1. Give the servers AWS credentials — Each Depotex server needs its own AWS credentials: an instance profile, an EKS or ECS task role, or the AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY environment variables.
2. Allow them to send — Attach a policy like the one below to those credentials, or to the role Depotex assumes.
3. Choose AWS credentials (IAM role) — Under Provider, choose Amazon SES, then AWS credentials (IAM role). The server and credentials fields are replaced by AWS credentials.
4. Pick the region — The SES region your verified identity is in.
5. Optionally, a role to assume — Enter a Role to assume (for example arn:aws:iam::123456789012:role/depotex-mail) when sending happens in another account or with a narrower role. Depotex assumes it with the server's own credentials and renews it before it expires. Enter the External ID only when the role's trust policy asks for one.
6. Send a test email — As for any provider. The Delivery check in the system check also confirms the credentials work and the SES account may send.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["ses:SendEmail", "ses:SendRawEmail"],
      "Resource": "arn:aws:ses:eu-west-1:123456789012:identity/example.com"
    },
    {
      "Effect": "Allow",
      "Action": "ses:GetAccount",
      "Resource": "*"
    }
  ]
}

ses:GetAccount is optional: the system check uses it to see whether the account is allowed to send. Without it, the check only confirms the credentials work. With a role to assume, the servers' own credentials also need sts:AssumeRole on that role, and the role's trust policy must allow them.

Security: use STARTTLS (port 587) or TLS (port 465). None sends passwords and messages unencrypted and is meant only for a relay on the same machine or a trusted network. Don't check the server certificate is for test labs only.

6. Fields

7. Troubleshooting

8. Configuration

9. Events

mail.settings.update is raised before and after the settings change, with whether it sends over SMTP or the Amazon SES API (never with the password). Password resets and invitations raise user.password.recover and user.invitation.accept. See Events.