listing

README

listing

About

Listing is a small and simple service that allows to self-host email subscriptions list on AWS using Lambda, DynamoDB, SES and SNS. It handles email list subscribe/unsubscribe/confirm actions as well as email bounces and complaints (if you use same SES account for sending the newsletter).

What problem it solves

Self-hosted email marketing solutions one can find today like tinycampaign, audience, mail-for-good, colossus and others have a few problems:

• a need to run a webserver all of the time (resources are expensive)
• operational overhead (certificate, updates, security)
• they solve too many problems at the same time (subscription list, email sending, analytics, A/B testing, email templates)

There's also a MoonMail which is kind of a good approximation of a better system, but it is too complex to deploy and it tries to solve all problems at the same time as well. And there is almost no documentation since they are interested in selling SaaS version of it.

Listing is different. It focuses only on building a subscription list. It is simple, well documented, tested and easy to install.

As for other functionality, you can achieve analytics and A/B testing using systems like Plausible or others. Finding good email templates or building ones using available tools is also not a problem. And there are many ways you can send those emails without a need to waste cloud computer resources at all other times.

How does it work

Listing manages arbitrary amounts of subscription lists using a few lambda functions and a DynamoDB table.

Listing uses so-called "double-confirmation" system where a user has to confirm it's email even after entering it on your website and pressing "Subscribe" button. The reason is that this is way more reliable in terms of loyal audience building.

Subscriptions are stored in a DynamoDB table and are managed by a lambda function with endpoints /subscribe, /unsubscribe, /confirm and /subscribers. The last endpoint is protected with BasicAuth for "admin" access (export/import of subscribers).

See also detailed endpoints docs

Bounces and Complaints are stored in an additional DynamoDB table. This table is managed by another lambda function that is subscribed to SNS topic. AWS SES for a specific domain is a publisher to this SNS topic.

How to use Listing

1. Deploy Listing (described below)
2. Test from the command line that everything works as expected (described below)
3. Create html form for your website to subscribe to emails using Listing Lambda URL

Everything else (confirmation, unsubscribe) will be handled in the emails or automatically.

In order to operate Listing you can use listing-cli command line application that allows you to export and import subscribers, subscribe/unsubscribe single email and other actions.

Install cli using: go install gitlab.com/ribtoks/listing/listing-cli@latest

See full cli documentation.

In order to send emails, you can use listing-send command line application that allows you to send templated html and text emails to recepients in previously exported list.

Install send using: go install gitlab.com/ribtoks/listing/listing-send@latest

See full send documentation.

How to avoid vendor lock

Listing is heavily dependent on AWS, but the size of DynamoDB table even with 100k subscribers is so small, you can safely export it to json using /subscribers endpoint and restore to any other cloud.

Listing uses serverless framework so migration to a different cloud will be less painful than from barebones AWS SAM templates.

Deployment

TL;DR; Copy secrets.example.yml to secrets.<your-deployment>.yml (your deployment can be as simple as prod or it can be per business logic unit). Then deploy using STAGE=<your-deployment> REGION=<region> make deploy-all.

See full documentation.

Testing

See full documentation.