Recently, I needed to replace the default SMTP service in ODK Central on DigitalOcean with AWS SES. I want to share my recommendations for setting up this functionality, as I found limited information available online during my search.
Configuring ODK Central with Amazon SES for SMTP Messaging
This guide will help you set up a custom email service in ODK Central using Amazon Simple Email Service (SES).
Prerequisites
- Access to the AWS SES console.
- A server running ODK Central.
Configuration Steps
1. Initial Setup for Amazon SES
Before proceeding, complete the initial setup tasks in the AWS SES console:
- Verify a sending domain: Ensure the domain you intend to use for sending emails is verified.
- Verify email addresses: Verify any email addresses you plan to use.
- Request production access (optional but recommended): This allows you to send emails to unverified recipients.
2. Create an SMTP User in Amazon SES
-
Navigate to the Amazon SES SMTP settings section in the AWS console.
-
Click on Create SMTP credentials.
-
Specify an IAM username and permissions. By default, AWS will create a permission group named
AWSSESSendingGroupDoNotRename
with the following policy:{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "ses:SendRawEmail", "Resource": "*" } ] }
-
After creating the SMTP user:
- The credentials will be displayed only once.
- Download the credentials as a
.csv
file. This file will contain:IAM user name
SMTP user name
SMTP password
3. Edit the .env
File in ODK Central
-
Connect to your server running ODK Central.
-
Edit the
.env
file (usually located in the~/central
directory) to include the custom mail server parameters.Example configuration:
EMAIL_FROM=no-reply@example.com # Your verified email address in SES EMAIL_HOST=email-smtp.us-east-1.amazonaws.com # Update based on your SES region EMAIL_PORT=587 # Typically 587 or 465 EMAIL_IGNORE_TLS=false # Do not ignore TLS EMAIL_SECURE=false # Use 'true' if using port 465 EMAIL_USER=your-smtp-username # Your SES SMTP username, NOT your IAM user name EMAIL_PASSWORD=your-smtp-password # Your SES SMTP password
Note: For more details, refer to the official documentation.
4. Rebuild and Restart the Containers
To apply the changes, execute the following commands on your server:
cd central
docker compose stop
docker compose build
docker compose up -d
5. Test Email Sending
- Log in to the ODK Central user interface.
- Perform an action that triggers an email, such as resetting a password.
- Verify that the email is received at the intended recipient's address.