Skip to content
The SimpleLogin back-end, including webapp and email handler.
CSS JavaScript Python HTML
Branch: master
Clone or download
Latest commit 9b9a3e7 Jan 28, 2020
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github/workflows only run Github action on Python 3.6 Jan 20, 2020
app fix formatting Jan 27, 2020
docs Improve README Jan 1, 2020
local_data add DKIM_PUBLIC_KEY_PATH setting Dec 29, 2019
migrations Add Directory model and add directory_id column to GenEmail Jan 8, 2020
static add paddle.js as a backup to their CDN Jan 10, 2020
templates Improve email copy Jan 22, 2020
tests add can_be_used_as_personal_email() Jan 25, 2020
.dockerignore Improve the Dockerfile Jan 23, 2020
.gitignore ignore config symlink Dec 15, 2019
CHANGELOG v1.0.1 - improve the self-hosting instructions Jan 27, 2020
Dockerfile Install requirements first and then copy the code to make good use of Jan 23, 2020
LICENSE add MIT License Dec 18, 2019 v1.0.1 - improve the self-hosting instructions Jan 27, 2020 add some stats directly to email subject when sending stats Dec 22, 2019
crontab.yml remove unused files Dec 18, 2019 Merge branch 'master' into notify-user-reply Jan 22, 2020
example.env rename .env.example to example.env Jan 23, 2020
pyproject.toml add black config Dec 22, 2019 add flask-profiler to requirements Jan 1, 2020
requirements.txt Merge pull request #16 from simple-login/lifetime Jan 1, 2020 fix test Jan 16, 2020 improve email: add <!doctype html>, use Hi {name} greeting Dec 15, 2019 create BaseForm to enable CSRF Jul 2, 2019

SimpleLogin | Privacy-First Email Forwarding and Identity Provider Service

Yet another email forwarding service?

In some way yes... However, SimpleLogin is a bit different because:

  • Fully open source: both the server and client code (browser extension, JS library) are open source so anyone can freely inspect and (hopefully) improve the code.

  • The only email forwarding solution that is self-hostable: with our detailed self-hosting instructions and most of components running as Docker container, anyone who knows ssh is able to deploy SimpleLogin on their server.

  • Not just email alias: SimpleLogin is a privacy-first and developer-friendly identity provider that:

    • offers privacy for users
    • is simple to use for developers. SimpleLogin is a privacy-focused alternative to the "Login with Facebook/Google/Twitter" buttons.
  • Plenty of features: browser extension, custom domain, catch-all alias, OAuth libraries, etc.

  • Open roadmap at you know the exciting features we are working on.

At the heart of SimpleLogin is email alias: an alias is a normal email address but all emails sent to an alias are forwarded to your email inbox. SimpleLogin alias can also send emails: for your contact, the alias is therefore your email address. Use alias whenever you need to give out your email address to protect your online identity. More info on our website at

Quick start

If you have Docker installed, run the following command to start SimpleLogin local server:

docker run --name sl -it --rm \
    -e RESET_DB=true \
    -e CONFIG=/code/example.env \
    -p 7777:7777 \
    simplelogin/app:1.0.1 python

Then open http://localhost:7777, you should be able to login with account!

To use SimpleLogin aliases, you need to deploy it on your server with some DNS setup though, the following section will show a step-by-step guide on how to get your own email forwarder service!

Table of Contents

1. General Architecture

2. Self Hosting

3. Contributing Guide

General Architecture

SimpleLogin backend consists of 2 main components:

  • the webapp used by several clients: web UI (the dashboard), browser extension (Chrome & Firefox for now), OAuth clients (apps that integrate "Login with SimpleLogin" button) and mobile app (work in progress).

  • the email handler: implements the email forwarding (i.e. alias receiving email) and email sending (i.e. alias sending email).

Self hosting


  • a Linux server (either a VM or dedicated server). This doc shows the setup for Ubuntu 18.04 LTS but the steps could be adapted for other popular Linux distributions. As most of components run as Docker container and Docker can be a bit heavy, having at least 2 GB of RAM is recommended. The server needs to have the port 25 (email), 80, 443 (for the webapp), 22 (so you can ssh into it) open.

  • a domain that you can config the DNS. It could be a sub-domain. In the rest of the doc, let's say it's for the email and for SimpleLogin webapp. Please make sure to replace these values by your domain name whenever they appear in the doc. A trick we use is to download this README file on your computer and replace all occurrences by your domain.

  • [Optional] AWS S3, Sentry, Google/Facebook/Github developer accounts. These are necessary only if you want to activate these options.

Except for the DNS setup that is usually done on your domain registrar interface, all the below steps are to be done on your server. The commands are to run with bash (or any bash-compatible shell like zsh) being the shell. If you use other shells like fish, please make sure to adapt the commands.

Some utility packages

These packages are used to verify the setup. Install them by:

sudo apt install -y dnsutils


From Wikipedia

DomainKeys Identified Mail (DKIM) is an email authentication method designed to detect forged sender addresses in emails (email spoofing), a technique often used in phishing and email spam.

Setting up DKIM is highly recommended to reduce the chance your emails ending up in the recipient's Spam folder.

First you need to generate a private and public key for DKIM:

openssl genrsa -out dkim.key 1024
openssl rsa -in dkim.key -pubout -out

You will need the files dkim.key and for the next steps.

For email gurus, we have chosen 1024 key length instead of 2048 for DNS simplicity as some registrars don't play well with long TXT record.


Please note that DNS changes could take up to 24 hours to propagate. In practice, it's a lot faster though (~1 minute or so in our test). In DNS setup, we usually use domain with a trailing dot (.) at the end to to force using absolute domain.

MX record

Create a MX record that points to with priority 10.

To verify if the DNS works, the following command

dig @ mx

should return:	3600	IN	MX	10

A record

An A record that points to your server IP. To verify, the following command

dig @ a

should return your server IP.


Set up DKIM by adding a TXT record for with the following value:

v=DKIM1; k=rsa; p=PUBLIC_KEY

with PUBLIC_KEY being your but

  • remove the -----BEGIN PUBLIC KEY----- and -----END PUBLIC KEY-----
  • join all the lines on a single line.

For example, if your is

-----END PUBLIC KEY-----

then the PUBLIC_KEY would be abcdefgh.

To verify, the following command

dig @ txt

should return the above value.


From Wikipedia

Sender Policy Framework (SPF) is an email authentication method designed to detect forging sender addresses during the delivery of the email

Similar to DKIM, setting up SPF is highly recommended. Add a TXT record for with the value

v=spf1 mx -all

What it means is only your server can send email with domain. To verify, the following commonly

dig @ txt

should return the above value.


Now the boring DNS stuffs are done, let's do something more fun!

If you don't already have Docker installed on your server, please follow the steps on Docker CE for Ubuntu to install Docker.

Tips: if you are not using root user and you want to run Docker without the sudo prefix, add your account to docker group:

sudo usermod -a -G docker $USER

Prepare the Docker network

This Docker network will be used by the other Docker containers run in the next steps. Later, we will setup Postfix to authorize this network.

docker network create -d bridge \
    --subnet= \
    --gateway= \


This section shows how to run a Postgres database using Docker. At the end of this section, you will have a database username and password which will be used in the next steps.

If you have already had a Postgres database in use, you can skip this section and just copy the database configuration (i.e. host, port, username, password, database name).

Run a Postgres Docker container as your Postgres database server. Make sure to replace myuser and mypassword with something more secret 😎.

docker run -d \
    --name sl-db \
    -e POSTGRES_PASSWORD=mypassword \
    -e POSTGRES_USER=myuser \
    -e POSTGRES_DB=simplelogin \
    -p 5432:5432 \
    --network="sl-network" \

To test whether the database operates correctly or not, run the following command:

docker exec -it sl-db psql -U myuser simplelogin

you should be logged in the postgres console. Type exit to exit postgres console.


Install postfix and postfix-pgsql. The latter is used to connect Postfix and the Postgres database in the next steps.

sudo apt-get install -y postfix postfix-pgsql -y

Choose "Internet Site" in Postfix installation window then keep using the proposed value as System mail name in the next window.

Replace /etc/postfix/ with the following content. Make sure to replace by your domain.

smtpd_banner = $myhostname ESMTP $mail_name (Ubuntu)
biff = no

# appending .domain is the MUA's job.
append_dot_mydomain = no

# Uncomment the next line to generate "delayed mail" warnings
#delay_warning_time = 4h

readme_directory = no

# See -- default to 2 on
# fresh installs.
compatibility_level = 2

# TLS parameters
smtpd_tls_session_cache_database = btree:${data_directory}/smtpd_scache
smtp_tls_session_cache_database = btree:${data_directory}/smtp_scache

# See /usr/share/doc/postfix/TLS_README.gz in the postfix-doc package for
# information on enabling SSL in the smtp client.

smtpd_relay_restrictions = permit_mynetworks permit_sasl_authenticated defer_unauth_destination
myhostname =
alias_maps = hash:/etc/aliases
alias_database = hash:/etc/aliases
mydestination = localhost
relayhost =
mynetworks = [::ffff:]/104 [::1]/128
mailbox_size_limit = 0
recipient_delimiter = +
inet_interfaces = all
inet_protocols = all
mydomain =
myorigin =
relay_domains = pgsql:/etc/postfix/
transport_maps = pgsql:/etc/postfix/
smtpd_delay_reject = yes
smtpd_helo_required = yes
smtpd_helo_restrictions = permit_mynetworks, reject_non_fqdn_helo_hostname, reject_invalid_helo_hostname, permit
smtpd_sender_restrictions = permit_mynetworks, reject_non_fqdn_sender, reject_unknown_sender_domain, permit
smtpd_recipient_restrictions = reject_unauth_pipelining, reject_non_fqdn_recipient, reject_unknown_recipient_domain, permit_mynetworks, reject_unauth_destination, reject_rbl_client, reject_rbl_client, permit

Create the /etc/postfix/ file with the following content. Make sure that the database config is correctly set and replace with your domain.

# postgres config
hosts = localhost
user = myuser
password = mypassword
dbname = simplelogin

query = SELECT domain FROM custom_domain WHERE domain='%s' AND verified=true UNION SELECT '%s' WHERE '%s' = '' LIMIT 1;

Create the /etc/postfix/ file with the following content. Again, make sure that the database config is correctly set and replace with your domain.

# postgres config
hosts = localhost
user = myuser
password = mypassword
dbname = simplelogin

# forward to smtp: for custom domain AND email domain
query = SELECT 'smtp:' FROM custom_domain WHERE domain = '%s' AND verified=true UNION SELECT 'smtp:' WHERE '%s' = '' LIMIT 1;

Finally, restart Postfix

sudo systemctl restart postfix

Run SimpleLogin Docker containers

To run the server, you need a config file. Please have a look at config example for an example to create one. Some parameters are optional and are commented out by default. Some have "dummy" values, fill them up if you want to enable these features (Paddle, AWS, etc).

Let's put your config file at ~/simplelogin.env. Below is an example that you can use right away, make sure to replace by your domain and set FLASK_SECRET to a secret string.

Make sure to update the following variables and replace these values by yours.

# WebApp URL

# domain used to create alias

# transactional email is sent from this email address

# custom domain needs to point to these MX servers

# By default, new aliases must end with ".{random_word}". This is to avoid a person taking all "nice" aliases.
# this option doesn't make sense in self-hosted. Set this variable to disable this option.

# If you want to use another MTA to send email, you could set the address of your MTA here
# By default, emails are sent using the the same Postfix server that receives emails

# the DKIM private key used to compute DKIM-Signature

# the DKIM public key used to setup custom domain DKIM

# DB Connection


Before running the webapp, you need to prepare the database by running the migration

docker run --rm \
    --name sl-migration \
    -v $(pwd)/dkim.key:/dkim.key \
    -v $(pwd)/ \
    -v $(pwd)/simplelogin.env:/code/.env \
    --network="sl-network" \
    simplelogin/app:1.0.1 flask db upgrade

This command could take a while to download the simplelogin/app docker image.

Now, it's time to run the webapp container!

docker run -d \
    --name sl-app \
    -v $(pwd)/simplelogin.env:/code/.env \
    -v $(pwd)/dkim.key:/dkim.key \
    -v $(pwd)/ \
    -p 7777:7777 \
    --network="sl-network" \

Next run the email handler

docker run -d \
    --name sl-email \
    -v $(pwd)/simplelogin.env:/code/.env \
    -v $(pwd)/dkim.key:/dkim.key \
    -v $(pwd)/ \
    -p 20381:20381 \
    --network="sl-network" \
    simplelogin/app:1.0.1 python


Install Nginx

sudo apt-get install -y nginx

Then, create /etc/nginx/sites-enabled/simplelogin with the following lines:

server {

    location / {
        proxy_pass http://localhost:7777;

Reload Nginx with the command below

sudo systemctl reload nginx

At this step, you should also setup the SSL for Nginx. Certbot can be a good option if you want a free SSL certificate.


If all of the above steps are successful, open and create your first account!

By default, new accounts are not premium so don't have unlimited alias. To make your account premium, please go to the database, table "users" and set "lifetime" column to "1" or "TRUE".

You don't have to pay anything to SimpleLogin to use all its features. You could make a donation to SimpleLogin on our Patreon page at if you wish though.


All work on SimpleLogin happens directly on GitHub.

Run code locally

The project uses Python 3.7+. First, install all dependencies by running the following command. Feel free to use virtualenv or similar tools to isolate development environment.

pip3 install -r requirements.txt

Then make sure all tests pass


To run the code locally, please create a local setting file based on example.env:

cp example.env .env

Make sure to uncomment the RESET_DB=true to create the database locally.

Feel free to custom your .env file, it would be your default setting when developing locally. This file is ignored by git.

You don't need all the parameters, for example, if you don't update images to s3, then BUCKET, AWS_ACCESS_KEY_ID can be empty or if you don't use login with Github locally, GITHUB_CLIENT_ID doesn't have to be filled. The example.env file contains minimal requirement so that if you run:


then open http://localhost:7777, you should be able to login with the following account / password


SimpleLogin current API clients are Chrome/Firefox/Safari extension and mobile (iOS/Android) app. These clients rely on API Code for authentication.

Once the Api Code is obtained, either via user entering it (in Browser extension case) or by logging in (in Mobile case), the client includes the api code in Authentication header in almost all requests.

For some endpoints, the hostname should be passed in query string. hostname is the the URL hostname (cf, for ex if URL is then the hostname is This information is important to know where an alias is used in order to suggest user the same alias if they want to create on alias on the same website in the future.

If error, the API returns 4** with body containing the error message, for example:

  "error":  "request body cannot be empty"

The error message could be displayed to user as-is, for example for when user exceeds their alias quota. Some errors should be fixed during development however: for example error like request body cannot be empty is there to catch development error and should never be shown to user.

All following endpoint return 401 status code if the API Key is incorrect.

GET /api/user_info

Given the API Key, return user name and whether user is premium. This endpoint could be used to validate the api key.


  • Authentication header that contains the api key

Output: if api key is correct, return a json with user name and whether user is premium, for example:

	"name": "John Wick",
	"is_premium": false

If api key is incorrect, return 401.

GET /api/v2/alias/options

User alias info and suggestion. Used by the first extension screen when user opens the extension.


  • Authentication header that contains the api key
  • (Optional but recommended) hostname passed in query string.

Output: a json with the following field:

  • can_create: boolean. Whether user can create new alias
  • suffixes: list of string. List of alias suffix that user can use. If user doesn't have custom domain, this list has a single element which is the alias default domain (
  • prefix_suggestion: string. Suggestion for the alias prefix. Usually this is the website name extracted from hostname. If no hostname, then the prefix_suggestion is empty.
  • existing: list of string. List of existing alias.
  • recommendation: optional field, dictionary. If an alias is already used for this website, the recommendation will be returned. There are 2 subfields in recommendation: alias which is the recommended alias and hostname is the website on which this alias is used before.

For ex:

    "can_create": true,
    "existing": [
    "prefix_suggestion": "test",
    "recommendation": {
        "alias": "",
        "hostname": ""
    "suffixes": [

POST /api/alias/custom/new

Create a new custom alias.


  • Authentication header that contains the api key
  • (Optional but recommended) hostname passed in query string
  • Request Message Body in json (Content-Type is application/json)
    • alias_prefix: string. The first part of the alias that user can choose.
    • alias_suffix: should be one of the suffixes returned in the GET /api/v2/alias/options endpoint.

Output: If success, 201 with the new alias, for example

  "alias": ""

POST /api/alias/random/new

Create a new random alias.


  • Authentication header that contains the api key
  • (Optional but recommended) hostname passed in query string

Output: If success, 201 with the new alias, for example

  "alias": ""

POST /api/auth/login


  • email
  • password
  • device: device name. Used to create the API Key. Should be humanly readable so user can manage later on the "API Key" page.


  • name: user name, could be an empty string
  • mfa_enabled: boolean
  • mfa_key: only useful when user enables MFA. In this case, user needs to enter their OTP token in order to login.
  • api_key: if MFA is not enabled, the api key is returned right away.

The api_key is used in all subsequent requests. It's empty if MFA is enabled. If user hasn't enabled MFA, mfa_key is empty.

POST /api/auth/mfa


  • mfa_token: OTP token that user enters
  • mfa_key: MFA key obtained in previous auth request, e.g. /api/auth/login
  • device: the device name, used to create an ApiKey associated with this device


  • name: user name, could be an empty string
  • api_key: if MFA is not enabled, the api key is returned right away.

The api_key is used in all subsequent requests. It's empty if MFA is enabled. If user hasn't enabled MFA, mfa_key is empty.

Database migration

The database migration is handled by alembic

Whenever the model changes, a new migration has to be created

Set the database connection to use a current database (i.e. the one without the model changes you just made), for example, if you have a staging config at ~/config/simplelogin/staging.env, you can do:

ln -sf ~/config/simplelogin/staging.env .env

Generate the migration script and make sure to review it before committing it. Sometimes (very rarely though), the migration generation can go wrong.

flask db migrate

In local the database creation in Sqlite doesn't use migration and uses directly db.create_all() (cf fake_data() method). This is because Sqlite doesn't handle well the migration. As sqlite is only used during development, the database is deleted and re-populated at each run.

Code structure

The repo consists of the three following entry points:

  • and the webapp.
  • the email handler.
  • the cronjob.

Here are the small sum-ups of the directory structures and their roles:

  • app/: main Flask app. It is structured into different packages representing different features like oauth, api, dashboard, etc.
  • local_data/: contains files to facilitate the local development. They are replaced during the deployment.
  • migrations/: generated by flask-migrate. Edit these files will be only edited when you spot (very rare) errors on the database migration files.
  • static/: files available at /static url.
  • templates/: contains both html and email templates.
  • tests/: tests. We don't really distinguish unit, functional or integration test. A test is simply here to make sure a feature works correctly.

The code is formatted using, to format the code, simply run


OAuth flow

SL currently supports code and implicit flow.

Code flow

To trigger the code flow locally, you can go to the following url after running python


You should see there the authorization page where user is asked for permission to share their data. Once user approves, user is redirected to this url with an authorization code: http://localhost:7000/callback?state=123456&code=the_code

Next, exchange the code to get the token with {code} replaced by the code obtained in previous step. The http tool used here is

http -f -a client-id:client-secret http://localhost:7777/oauth/token grant_type=authorization_code code={code}

This should return an access token that allows to get user info via the following command. Again, http tool is used.

http http://localhost:7777/oauth/user_info 'Authorization:Bearer {token}'

Implicit flow

Similar to code flow, except for the the access token which we we get back with the redirection. For implicit flow, the url is


OpenID and OAuth2 response_type & scope

According to the sharing web blog titled Diagrams of All The OpenID Connect Flows, we should pay attention to:

  • response_type can be either code, token, id_token or any combination of those attributes.
  • scope might contain openid

Below are the potential combinations that are taken into account in SL until now:

	    with `openid` in scope, return `id_token` at /token: OK
	    without: OK

	    with and without `openid`, nothing to do: OK

    return `id_token` in /authorization endpoint

response_type=id_token token
    return `id_token` in addition to `access_token` in /authorization endpoint

response_type=id_token code
    return `id_token` in addition to `authorization_code` in /authorization endpoint

❤️ Contributors

Thanks go to these wonderful people:

Dung Nguyen Van
Dung Nguyen Van

Giuseppe Federico
Giuseppe Federico

Ninh Dinh
Ninh Dinh

Tung Nguyen V. N.
Tung Nguyen V. N.

Son Nguyen Kim
Son Nguyen Kim

You can’t perform that action at this time.