johndope/mail-server repository overview

   __  ___     _ __  ____                    
  /  |/  /__ _(_) / / __/__ _____  _____ ____
 / /|_/ / _ `/ / / _\ \/ -_) __/ |/ / -_) __/
/_/  /_/\_,_/_/_/ /___/\__/_/  |___/\__/_/   
                                             

Completely FREE and Open Source like Mail In A Box⁠, Docker Mailserver⁠, Mailu⁠ and Maddy Mail Server⁠, but DOESN'T REQUIRE posessing a domain, DOESN'T REQUIRE loads of docker compose configurations and DOESN'T REQUIRE a HTTPS certificate.

⁠Features

• 🔥 RESTful API, basic url request in any coding language;
• 📧 Authentic, send actual emails (looking at you, mailhog);
• 🔐 Secure, force SSL encryption when sending mails;
• ✨ Lightweight yet Reliable, use SMTP under the hood;
• 🚀 OOTB, working out-of-the-box with almost zero config;
• 🐳 Docker Ready, start your service in less than 1 minute;
• ⚛️ Heroku Ready, deploy your service in less than 1 minute.

⁠Get Started

read -p "Password: " -s password && \
docker run --rm -it -p <LOCAL_PORT>:8080 \
    -e "NAME=<DISPLAY_SENDER_NAME>" \
    -e "EMAIL=<[email protected]>" \
    -e "PASSWORD=${password}" \
    johndope/mail-server:latest

⁠Providers

Email addresses from these 4 SMTP mail service providers can be automatically configured: Gmail⁠, Yandex⁠, QQ (Tencent)⁠ and 163 (NetEase)⁠.

NOTICE:

• Use the APP password⁠ for Gmail password;
• Use the Auth Code⁠ (Settings - POP3/SMTP/IMAP - Auth Code Management) for NetEase password.

⁠Use other providers

Mail Server⁠ also supports custom provider configurations, just add the SMTP_DOMAIN (eg. smtp.gmail.com) and SMTP_SSL_PORT (eg. 465) env variables.

⁠Basic Usage

Here's a simple example for Python users:

import requests

resp = requests.get(SERVER_INSTANCE, params={
    'subject': 'Please validate your email address',
    'receiver': [RECEIVER_EMAIL, ANOTHER_RECEIVER_EMAIL],
    'html': f'<h1>Hello from {BRAND_NAME}!</h1>',
})
resp.raise_for_status()
print(resp.json())

⁠Templates

Mail Server⁠ also supports templates. Mail Server⁠ ships with a default template⁠ (for new registered account activation), to use this template:

activation_template_args = {
    'username': 'John Theo',
    'activation_link': 'https://github.com/john-theo',
    'brand_name': BRAND_NAME,
    'contact_email': RECEIVER_EMAIL,
}
resp = requests.post(SERVER_INSTANCE, data={
    'subject': 'Please validate your email address',
    'receiver': [RECEIVER_EMAIL],
    'template': 'activation',
    **activation_template_args
}, files=[
    ('attachments', ('activation.jinja', open('templates/activation.jinja', 'rb'))),
    ('attachments', ('server.py', open('src/server.py', 'rb')))
])
resp.raise_for_status()
print(resp.json())

You can also mount your own templates into the docker container and use them.

⁠Template Debugging

To debug your own templates, you can use the /debug (backward compatibility) or the /preview endpoint with the same request payload, it will response the renderer HTML page with parsed parameters at the bottom.

⁠TOTP

TOTP, or time-based one-time password, is the algorithm commonly used by authenticators for 2FA, it generates a one-time password that uses the current time as a source of uniqueness.

If you deploy Mail Server⁠ to a publicly accessible domain (like Heroku), anyone can send emails on your behalf which is highly dangerous. So to enable TOTP to reject requests not send by your trusted backends:

1. add a TOTP_SECRET env variable;
2. tell your good backend pal this secret key and ask them to send requests with a query parameter totp (eg. GET /?totp=072813).

⁠How to generate the TOTP secret key

To generate a secret key run:

docker run --rm -it \
    johndope/mail-server:latest \
    bash generate_totp.sh

⁠Deploy

1. Clone this repository
2. Fill in the blanks in the .env file
3. Run make hinit && make hpush

⁠Quick reference

• Maintained by: John Dope⁠
• Code repository: https://github.com/john-theo/MailServer⁠
• Issues: https://github.com/john-theo/MailServer/issues⁠
• Docker Hub: https://hub.docker.com/r/johndope/mail-server⁠

⁠License

Mail Server⁠ by John Dope⁠ is licensed under Attribution-NonCommercial-ShareAlike 4.0 International⁠