AWS SMTP Relay

SMTP server to relay emails via AWS SES API using IAM roles.

Contents

• Background
• Docker
• Installation
• Usage
  • Options
  • TLS
  • Region
  • Credentials
  • Logging
• Development
  • Requirements
  • Build
  • Test
  • Install
  • Uninstall
  • Clean
• Credits
• License

Background

AWS SES provides both an API and an SMTP interface to send emails.

The SMTP interface is useful for applications that must use SMTP to send emails, but it requires providing a set of SES SMTP Credentials.

For security reasons, using IAM roles is preferable, but only possible with the SES API and not the SMTP interface.

This is where this project comes into play, as it provides an SMTP interface that relays emails via SES API using IAM roles.

Docker

This repository provides a sample Dockerfile to build and run the project in a container environment.

A prebuilt Docker image is also available on Docker Hub:

docker pull blueimp/aws-smtp-relay

Installation

The aws-smtp-relay binary can be installed from source via go get:

go get github.com/blueimp/aws-smtp-relay

Usage

By default, aws-smtp-relay listens on port 1025 on all interfaces when started without arguments:

aws-smtp-relay

Options

Available options can be listed the following way:

aws-smtp-relay --help

Usage of aws-smtp-relay:
  -a string
    	TCP listen address (default ":1025")
  -c string
    	TLS cert file
  -h string
    	Server hostname
  -k string
    	TLS key file
  -n string
    	SMTP service name (default "AWS SMTP Relay")
  -s	Require TLS via STARTTLS extension
  -t	Listen for incoming TLS connections only

TLS

Edit the openssl config file and change localhost to your server hostname.

Generate a self-signed certificate with a passphrase encrypted key:

openssl req -new -x509 -config tls/openssl.conf -days 24855 \
  -out tls/default.crt \
  -keyout /dev/stdout |
  openssl rsa -aes256 -out tls/default.key

Please note:

Encrypted key files are only supported if they contain a DEK-Info header, stating the encryption method used.
The openssl req command does not create this header if encryption is enabled, which is why we pipe the unencrypted key output to the openssl rsa command, which outputs an encrypted key file with the required DEK-Info header.

The key file passphrase must be provided as TLS_KEY_PASS environment variable:

TLS_KEY_PASS=$PASSPHRASE aws-smtp-relay -c tls/default.crt -k tls/default.key

Region

The AWS_REGION must be set to configure the AWS SDK, e.g. by executing the following command before starting aws-smtp-relay:

export AWS_REGION=eu-west-1

Credentials

On EC2 or ECS, security credentials for the IAM role are automatically retrieved:

• IAM Roles for Amazon EC2
• IAM Roles for Tasks

Logging

Requests are logged in JSON format to stdout with an empty Error property:

{
  "Time": "2018-04-18T15:08:42.4388893Z",
  "IP": "172.17.0.1",
  "From": "alice@example.org",
  "To": [
    "bob@example.org"
  ],
  "Error": ""
}

Errors are logged in the same format to stderr, with the Error property set:

{
  "Time": "2018-04-18T15:08:42.4388893Z",
  "IP": "172.17.0.1",
  "From": "alice@example.org",
  "To": [
    "bob@example.org"
  ],
  "Error": "MissingRegion: could not find region configuration"
}

Development

Requirements

First, clone the project via go get and then switch into its source directory:

go get github.com/blueimp/aws-smtp-relay
cd "$GOPATH/src/github.com/blueimp/aws-smtp-relay"

Please note:
This project relies on vgo for automatic dependency resolution.

To use the original go tool instead, export the following environment variable:

export GO_CLI=go

And install the project dependencies:

go get ./...

Build

To build the project, run Make in the repository directory, which creates the aws-smtp-relay binary:

make

Test

All components come with unit tests, which can be executed the following way:

make test

Sending mails can also be tested with the provided mail shell script:

echo TEXT | ./mail.sh -p 1025 -f alice@example.org -t bob@example.org

See also Testing Amazon SES Email Sending.

Install

The binary can also be built and installed in $GOPATH/bin/ with the following command:

make install

Uninstall

The uninstall command removes the binary from $GOPATH/bin/:

make uninstall

Clean

To remove any build artifacts, run the following:

make clean

Credits

Includes the smtpd package by Mark Hale.

License

Released under the MIT license.