HUB
Sign inSign up

johndope/mail-server

By johndope

•Updated over 4 years ago

Free email server, available everywhere, without all the pains on domains and certificates.

Image
0

260

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.

Notice: DO NOT use this project in large-scale production environments.

⁠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

There will be a prompt for "Password", paste your Email password and hit enter (whatever you paste or input will not be shown on the screen).

⁠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).

There are packages in various languages that can generate the TOTP token like ROTP⁠ for Ruby, PyTOP⁠ for Python, OTPlib⁠ for Nodejs and many more.

⁠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

⁠License

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

Tag summary

Content type

Image

Digest

Size

22.8 MB

Last updated

over 4 years ago

docker pull johndope/mail-server