Configuring ODK Central to use Amazon SES for email sending

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

  1. Access to the AWS SES console.
  2. 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

  1. Navigate to the Amazon SES SMTP settings section in the AWS console.

  2. Click on Create SMTP credentials.

  3. 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": "*"
            }
        ]
    }
    
  4. 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

  1. Connect to your server running ODK Central.

  2. 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

  1. Log in to the ODK Central user interface.
  2. Perform an action that triggers an email, such as resetting a password.
  3. Verify that the email is received at the intended recipient's address.
3 Likes