README
¶
AWS SMTP Relay
SMTP server to relay emails via Amazon SES or Amazon Pinpoint using IAM roles.
⚠️ Fork Notice
This repository is a maintained fork of blueimp/aws-smtp-relay, which appears to be inactive. This fork includes:
- Active maintenance and support for pending pull requests
- Cross-account SES authorization support via ARN parameters
- Multi-architecture Docker images (amd64, arm64)
- Dual registry publishing to Docker Hub and GitHub Container Registry
Pull requests and contributions are welcome!
Contents
Background
Amazon SES and Amazon Pinpoint both provide 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 SMTP credentials:
For security reasons, using IAM roles is preferable, but only possible with the Email 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 or Pinpoint API using IAM roles.
Docker
This repository provides Dockerfile and Dockerfile.alpine to build and run the project in a container environment.
Prebuilt multi-architecture Docker images (amd64, arm64, armv7) are available on both registries:
- Docker Hub: kamorion/aws-smtp-relay
- GitHub Container Registry:
ghcr.io/kamorionlabs/aws-smtp-relay
Available Image Tags
Production (Distroless - Recommended)
Minimal, secure images based on Google's Distroless base (no shell, no package manager):
# Stable releases
docker pull kamorion/aws-smtp-relay:latest # Latest stable release
docker pull kamorion/aws-smtp-relay:v1.2.3 # Specific version
docker pull kamorion/aws-smtp-relay:v1.2 # Latest patch of v1.2
docker pull kamorion/aws-smtp-relay:v1 # Latest minor of v1
# Development (from main branch)
docker pull kamorion/aws-smtp-relay:edge # Latest commit from main branch
Debug (Alpine - With Shell)
Images based on Alpine Linux, includes shell and basic debugging tools:
# Stable releases
docker pull kamorion/aws-smtp-relay:latest-alpine # Latest stable release
docker pull kamorion/aws-smtp-relay:v1.2.3-alpine # Specific version
# Development (from main branch)
docker pull kamorion/aws-smtp-relay:edge-alpine # Latest commit from main branch
Notes:
- All tags are available on both Docker Hub (
kamorion/) and GHCR (ghcr.io/kamorionlabs/) latesttag = last stable release (tagged withv*)edgetag = latest commit on main branch (bleeding edge, for testing)- Use distroless images for production (smaller, more secure)
- Use alpine images for debugging (includes shell access)
Quick Start
# Production (recommended)
docker run -d \
-p 1025:1025 \
-e AWS_REGION=eu-west-1 \
kamorion/aws-smtp-relay:latest
# Debug with shell access
docker run -d \
-p 1025:1025 \
-e AWS_REGION=eu-west-1 \
kamorion/aws-smtp-relay:latest-alpine
# Test bleeding edge
docker run -d \
-p 1025:1025 \
-e AWS_REGION=eu-west-1 \
kamorion/aws-smtp-relay:edge
Kubernetes/Helm
The Helm chart deploys the relay with the IAM role of its service account (EKS Pod Identity or IRSA), Prometheus metrics, health probes, a PodDisruptionBudget and optional autoscaling:
helm install aws-smtp-relay oci://ghcr.io/kamorionlabs/charts/aws-smtp-relay \
--namespace smtp --create-namespace \
--set config.awsRegion=eu-west-1
Each release publishes the chart with the same version as the relay. From a
clone, install ./helm/aws-smtp-relay instead.
See the EKS deployment guide for the IAM role and the Pod Identity association (Terraform or AWS CLI), and the chart README for all values.
Installation
Pre-compiled Binaries
Download pre-compiled binaries for your platform from GitHub Releases.
Available platforms:
- Linux (amd64, arm64, armv6, armv7)
- Windows (amd64, arm64)
- macOS (amd64, arm64)
From Source
The aws-smtp-relay binary can be installed from source via go install:
go install github.com/KamorionLabs/aws-smtp-relay@latest
Docker
See Docker section above for container images.
Usage
By default, aws-smtp-relay listens on port 1025 on all interfaces as open
relay (without authentication) 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
-d string
Denied recipient emails regular expression
-e string
Amazon SES Configuration Set Name
-h string
Server hostname
-i string
Allowed client IPs (comma-separated)
-k string
TLS key file
-l string
Allowed sender emails regular expression
-m string
HTTP listen address for /metrics and /healthz (off when empty)
-n string
SMTP service name (default "AWS SMTP Relay")
-r string
Relay API to use (ses|pinpoint) (default "ses")
-s Require TLS via STARTTLS extension
-t Listen for incoming TLS connections only
-u string
Authentication username
-w string
Allowed recipient emails regular expression
-W string
Allowed recipient domains (comma-separated)
Authentication
User
The supported user-based SMTP authentication mechanisms and their required configuration settings (see also RFC 4954):
| Mechanism | TLS | User | Hash | Pass |
|---|---|---|---|---|
LOGIN |
Yes | Yes | Yes | No |
PLAIN |
Yes | Yes | Yes | No |
CRAM-MD5 |
No | Yes | No | Yes |
Authentication can be enabled for LOGIN and PLAIN mechanisms by configuring
TLS and a username and providing the
bcrypt encrypted password as
BCRYPT_HASH environment variable:
export BCRYPT_HASH=$(htpasswd -bnBC 10 '' password | tr -d ':\n')
export TLS_KEY_PASS="$PASSPHRASE"
aws-smtp-relay -c tls/default.crt -k tls/default.key -u username
If the password is provided as plain text PASSWORD environment variable, it
will also enable the CRAM-MD5 authentication mechanism:
export PASSWORD=password
export TLS_KEY_PASS="$PASSPHRASE"
aws-smtp-relay -c tls/default.crt -k tls/default.key -u username
Without TLS configuration, only CRAM-MD5 will be enabled:
export PASSWORD=password
aws-smtp-relay -u username
Please note:
It is not recommended to provide the password as plain text environment variable, nor to configure the SMTP server without TLS support.
IP
To limit the allowed IP addresses, supply a comma-separated list via -i ips
option:
aws-smtp-relay -i 127.0.0.1,::1
Please note:
To authorize their IP, clients must use a supported SMTP authentication mechanism, e.g.
LOGINorPLAINvia TLS orCRAM-MD5on unencrypted connections. This is required even if no user authentication is configured on the server, although in this case the credentials can be chosen freely by the client.
TLS
Configure TLS with the following steps:
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-Infoheader, stating the encryption method used. Theopenssl reqcommand does not create this header if encryption is enabled, which is why we pipe the unencrypted key output to theopenssl rsacommand, which outputs an encrypted key file with the requiredDEK-Infoheader.
Provide the key file passphrase as TLS_KEY_PASS environment variable and the
cert and key file as command-line arguments:
TLS_KEY_PASS="$PASSPHRASE" aws-smtp-relay -c tls/default.crt -k tls/default.key
Please note:
It is recommended to require TLS via
STARTTLSextension (-soption flag) or to configure the server to listen for incoming TLS connections only (-toption flag).
Filtering
Senders
To limit the allowed sender email addresses, provide an allow list as
regular expression via -l regexp
option:
aws-smtp-relay -l '@example\.org$'
By default, all sender email addresses are allowed.
Recipients
To deny certain recipient email addresses, provide a deny list as
regular expression via -d regexp
option:
aws-smtp-relay -d 'admin@example\.org$'
To allow only certain recipient email addresses, provide an allow list as
regular expression via -w regexp
option, or the ALLOWED_RECIPIENTS_REGEX environment variable:
aws-smtp-relay -w '^[^@]+@example\.org$'
To allow only certain recipient domains, provide a comma-separated list via
-W domains option, or the ALLOWED_RECIPIENT_DOMAINS environment variable.
Domains match exactly and ignore case; subdomains must be listed on their own:
aws-smtp-relay -W 'example.org,mail.example.org'
A recipient is allowed only if it passes every filter that is set: it must not
match the -d deny list, it must match the -w regular expression, and its
domain must be in the -W list.
A denied recipient is refused at RCPT with 550, so the client can still
send the message to the other recipients.
By default, all recipient email addresses are allowed.
Cross-Account Authorization
For cross-account SES authorization, you can specify Amazon Resource Names (ARNs):
aws-smtp-relay -o arn:aws:ses:region:account-id:identity/example.com
Available ARN options:
-o: Amazon SES SourceArn (also used as default for FromArn and ReturnPathArn if not specified)-f: Amazon SES FromArn-p: Amazon SES ReturnPathArn
If only SourceArn (-o) is provided, it will automatically be used for FromArn and ReturnPathArn unless explicitly overridden.
SESv2 API ARN Mapping
This relay uses the Amazon SES v2 API which maps ARN parameters as follows:
-
FromArn or SourceArn →
FromEmailAddressIdentityArnUsed for sending authorization when the identity owner has granted you permission to send on their behalf. -
ReturnPathArn →
FeedbackForwardingEmailAddressIdentityArnUsed for bounce and complaint notifications. The ARN of the identity associated with the feedback forwarding address.
For more information about SESv2 sending authorization, see the Amazon SES Developer Guide.
See AWS SES Cross-Account Sending for more details.
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:
SMTP replies
The reply tells the SMTP client whether to try again:
| Result | Reply |
|---|---|
| The API accepted the message | 250 |
Denied sender (after DATA) |
550 5.7.1 |
Denied recipient (at RCPT) |
550 5.1.0 |
Throttling, a 429 or 5xx from the API, a network error or timeout |
451 4.3.0 |
An error of the setup: a 401 or 403 (e.g. AccessDenied), SendingPaused, AccountSuspended, MailFromDomainNotVerified |
451 4.3.0 |
Any other API error, e.g. MessageRejected |
554 5.0.0 |
A 4xx reply makes the client try again later. A 5xx reply makes it give up.
An error of the setup gets 451: after an operator fixes it, the same message
goes through, so the client keeps it and does not bounce it.
The 451 and 554 replies include only the API error code, for example
554 5.0.0 Message refused: MessageRejected. The log has the full error.
Metrics
To serve Prometheus metrics at /metrics, provide an
HTTP listen address with the -m addr option or the METRICS_ADDRESS
environment variable. The same address serves /healthz, which shows only that
the process runs:
aws-smtp-relay -m :9090
| Metric | Type | Description |
|---|---|---|
aws_smtp_relay_messages_total |
counter | Messages by result: sent, denied (by a filter) or error |
aws_smtp_relay_auth_failures_total |
counter | Failed SMTP authentications |
aws_smtp_relay_send_duration_seconds |
histogram | Time to handle a message, with the API request when there is one |
The relay sends a message with some denied recipients to the other
recipients, but counts it as denied.
The relay also serves the Go runtime and process metrics of the Prometheus client. By default, it serves no metrics.
Logging
Requests are logged in JSON format to stdout with the Error property set
to null:
{
"Time": "2018-04-18T15:08:42.4388893Z",
"IP": "172.17.0.1",
"From": "alice@example.org",
"To": ["bob@example.org"],
"Error": null
}
Errors are logged in the same format to stderr, with the Error property set
to a string value:
{
"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
Build
First, clone the project and then switch into its source directory:
git clone https://github.com/KamorionLabs/aws-smtp-relay.git
cd aws-smtp-relay
Please note:
This project relies on Go modules for automatic dependency resolution.
To build the project, run
Make in the repository
directory, which creates the aws-smtp-relay binary:
make
Lint
To lint the source code, first install staticcheck:
go install honnef.co/go/tools/cmd/staticcheck@latest
Then run the following command:
make lint
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
Please note:
The provided shell script only supports the
LOGINauthentication mechanism.
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
Release
The Release workflow tags the version, runs
GoReleaser (binaries, Docker Hub and GHCR images, GitHub release) and publishes
the Helm chart to oci://ghcr.io/kamorionlabs/charts. It starts:
- when a pull request with the label
release:patch,release:minororrelease:majoris merged intomain: the version is the latestvX.Y.Ztag with that part incremented; - from the Actions tab, with Run workflow on
main: choose the part to increment, or give an exact version; - when a
v*tag is pushed.
Pull requests without a release label are not released.
Dependencies
License
Released under the MIT license.
Documentation
¶
There is no documentation for this package.
Directories
¶
| Path | Synopsis |
|---|---|
|
internal
|
|
|
auth
Package auth provides an IP and user credentials based authentication handler.
|
Package auth provides an IP and user credentials based authentication handler. |
|
metrics
Package metrics counts the messages and failed logins of the relay and serves the counts for Prometheus.
|
Package metrics counts the messages and failed logins of the relay and serves the counts for Prometheus. |
|
relay
Package relay provides an interface to relay emails via Amazon SES/Pinpoint API.
|
Package relay provides an interface to relay emails via Amazon SES/Pinpoint API. |