A simple self hostable email inbox

• Table of Contents
• About The Project
  • Features
• Getting Started
  • Prerequisites
  • Installation
  • Running with docker
• Connecting to your domain
  • Example DNS configurations
• Configuration
• Sending
• API Reference
• License

Maildrop is a self hostable and easy to use email service that allows you to receive emails on any address on your domain.

It is perfect for:

• People who want to easily use multiple email addresses.
• Signing up for services without without using your main email address.
• Easily creating multiple accounts on websites.

• Random email generation
• Use custom emails
• Support for password protected inboxes
• Clean UI
• Easy setup
• Automatic inbox clearing
• (Optional) Sending Emails
  Set up sending

If you wish to install maildrop and run it with python, follow this guide, if you wish to install it with docker instead, then proceed to Running with Docker.

• Python 3
• uv (Installation Guide)

1. Clone the repository

   git clone https://github.com/haileyydev/maildrop.git
   cd maildrop

2. Sync dependencies

   uv sync

3. Run the application

   If the SMTP server runs on port 25, which it does by default, it must be run as root:

   sudo $(which uv) run maildrop

   Otherwise you do not need root:

   uv run maildrop

Maildrop will be running on port 5000 and the smtp server on port 25 unless configured otherwise.

Alternatively, you can run maildrop inside of a docker container using the official docker image.

Use this command to run maildrop in a docker container:

sudo docker run \
  -d \
  --restart unless-stopped \
  --name maildrop \
  -p 5000:5000 \
  -p 25:25 \
  -e DOMAIN="yourdomain.com" \
  haileyydev/maildrop:latest  

Or if you prefer docker compose, Add this to your compose.yml file:

services:
  maildrop:
    image: haileyydev/maildrop:latest
    container_name: maildrop
    restart: unless-stopped
    ports:
      - "5000:5000"
      - "25:25"
    environment:
      - DOMAIN=yourdomain.com

and then start it: sudo docker compose up -d

Follow this guide to set up receiving emails on your domain.

1. Ensure port 25 is open
   This is the port the smtp server uses. Some ISPs block this so you may need to use a tunnel or host maildrop in the cloud.
2. Create an A record in your dns settings
   Create this on the domain you want the maildrop running on. The ip address should be pointed to the public ip address of the server running maildrop.
3. Create an MX record in your dns settings
   Create this on the domain you want emails to be sent to. It should be pointed to the domain you created your A record on.
4. Edit .env and change the domain to your domain
   Edit the .env file and set DOMAIN to the domain you are receiving emails on (so the domain you created the MX record on). This is used for email address generation. If you are using docker, edit the DOMAIN environment variable directly.

This is what the dns configuration should look like once you have created the records.

If you are running maildrop on a different domain/subdomain than the one you are receiving emails on:

In this configuration, you would be able to access maildrop from http://maildrop.domain.com:5000 (or preferably https://maildrop.domain.com if you are running a reverse proxy with https)

If you are running maildrop on the same domain/subdomain than the one you are receiving emails on:

In this configuration, you would be able to access maildrop from http://domain.com:5000 (or preferably https://domain.com if you are running a reverse proxy with https)

Create a .env file and edit the values to change these, you can create a copy of .example.env for a template if you want. If you are using docker, simply set these as environment variables.

Maildrop also supports sending mail as an optional feature. Visit the Sending Guide for instructions.

Visit the API Reference for instructions on interacting with maildrop via the simple JSON API.

Distributed under the GNU General Public License v3.0.