00: A Self-Hostable Markdown Email Microservice for AWS SES

Introduction

00 is an innovative, self-hostable microservice built in Elixir, designed to transform your experience with AWS Simple Email Service (SES). While SES offers an incredibly affordable way to power email-heavy applications, monitoring and managing emails can often become a complex task, typically requiring custom infrastructure and a deep understanding of AWS pipelines.

This project addresses these challenges by providing a user-friendly dashboard for sending and monitoring emails, complete with multi-recipient tracking, search capabilities, and log tracking. It simplifies the initial setup by offering an SST configuration step to establish the SES, SNS, and SQS pipeline, allowing you to get started quickly without the usual AWS headaches.

Key features of 00 include:

Automated AWS configuration using SST.
The ability to send emails via a simple POST request to /api/emails.
Comprehensive email status monitoring, including multi-recipient tracking.
Powerful search functionality for emails and messages.
Detailed viewing of email bodies.
Robust log tracking for requests and queues.

Installation

Getting 00 up and running involves configuring AWS and deploying the Docker container.

Configure AWS

The quickest way to set up AWS is by using SST:

Clone the 00 repository.
Set the EMAIL_IDENTITY environment variable to the email or domain you wish to send from.
Run sst deploy in the cloned repository.

For detailed steps on using SST, refer to the SST CLI documentation and learn how to configure your credentials here.

Alternatively, you can manually configure AWS by setting up a configuration set to write to an SQS queue via SNS. More events sent to the queue will enable more comprehensive tracking by 00. A guide for manual AWS configuration is available here.

Both methods will provide an SQS URL and other necessary environment variables. Note that SST currently only deploys the SES pipeline, not the container itself.

Setup the Docker Container

00 provides a Docker image for easy deployment:

Pull the Docker image: docker pull liltechnomancer/double-zero
Run your Docker container, exposing port 4000 and setting the required environment variables. An example command is:

docker run -it --env-file .env -p 4000:4000 "liltechnomancer/double-zero"

Essential environment variables include:

AWS_SECRET_ACCESS_KEY=
AWS_ACCESS_KEY_ID=
AWS_REGION= # Ex: us-east-1
SQS_URL=  # Ex: https://sqs.us-east-1.amazonaws.com/${id}

SYSTEM_EMAIL= # For sending stuff like password resets. Ex: test@example.com should be able to send from SES.

SECRET_KEY_BASE= # A long secret. at least 64 characters.

DATABASE_PATH= # Path to SQLite database Ex: 00.db
PHX_HOST= # URL or IP of where this service is running. Ex: example.com

After setup, visit your configured URL (PHX_HOST) to register your user.

Verify your Domain

To ensure emails can be sent, you must verify your domain with SES:

Log into the AWS management Console.
Navigate to your SES Identities in the region where you set up SES.
Select the domain you wish to verify.
Scroll down to DomainKeys Identified Mail (DKIM) and open the Publish DNS records dropdown.
You will see three DNS records. Add these to your domain provider's DNS settings. Verification typically takes less than 12 hours.

Examples

Once 00 is running, you can start sending emails via its API.

Register an API Key

Log into your 00 instance.
Navigate to Settings.
Enter a unique name in the Token Name field.
Click on Create New API Token.
Save the displayed API key immediately, as it cannot be viewed again after closing the pop-up.

Make an API Request

To send an email, make a POST request to yourdomain.com/api/emails.

Set the Authorization Header to Bearer yourapikeyhere.
Include a JSON body representing your email.
Send the POST request.

A successful response will look like this:

{
    "data": {
        "id": "51c2df38-0e3d-458b-9aff-3bf872868695",
        "message": "Your email has successfully been queued.",
        "success": true
    }
}

Body Parameters

The request body must be JSON with the following parameters:

Param	Type	Required	Notes	Example
markdown	string	no	For the email body. Either `markdown` or `html` can be used.	`{"markdown":"Some Text"}`
html	string	no	For the email body. Either `markdown` or `html` can be used.	`{"html":"<h1>Some HTML</h1>"}`
subject	string	no	The email's subject field	`{"subject":"Some Subject"}`
from	string	yes	The email address from which the email is sent. Must be something@yourdomain.com, and the domain must be verified in SES.	`{"from":"noreply@yourdomain.com"}`
to	string/string[]	yes	The email's recipient(s)	`{"to":"joe@somedomain.com"}` or `{"to": ["joe@somedomain.com", "jane@somedomain.com"]}`
cc	string	no	"The email address to which a copy of the email will be sent."	`{"cc":"cc_address@yourdomain.com"}`
reply_to	string	no	The email address from which the reply will be sent.	`{"reply_to":"reply@yourdomain.com"}`
headers	object	no	An object containing key/value pairs of headers	`{"headers": {"X-Entity-Ref-ID": "00"}}`
provider_options	object	no	An object containing key/value pairs of provider options	`{"provider_options": {"tags": [{"name": "tag-name", "value": "some-value"}]}}`
attachments	array	no	An array containing attachments	`{"attachments": [{"filename": "invoice.txt", "content": "pewp", "content_type": "text/plain"}]}`

Example Request Body

{
  "html": "<h1>Hello world!</h1>",
  "subject": "Can your email service track multiple recipients?",
  "from": "levi@fidoforms.com",
  "to": ["levi@technomancy.dev", "complaint@simulator.amazonses.com"]
}

Why use 00?

00 offers a compelling solution for developers and organizations looking to leverage AWS SES without the typical operational overhead. Its key advantages include:

Simplified SES Management: It abstracts away the complexities of setting up and monitoring AWS SES, providing a streamlined experience.
Comprehensive Dashboard: Gain immediate visibility into email statuses, bounces, and other critical metrics through an intuitive web interface.
Easy Deployment: With Docker and SST, deploying and configuring 00 is straightforward, reducing setup time significantly.
Flexible Email Sending: Support for both Markdown and HTML email bodies, along with attachments and custom headers, offers great flexibility.
Open-Source and Self-Hostable: Enjoy full control over your email infrastructure with a robust, community-driven open-source project.