Skip to main content

🚀 Mailpit Installer

A simple shell script to install and manage Mailpit — a lightweight email testing tool — on Linux or macOS. 📨

✅ Maintained by Asif Ahmad Khan — mailpit-setup

This script:

  • 🗕️ Downloads the latest Mailpit release
  • 📂 Installs the binary to /usr/local/bin (or custom path)
  • 🔧 Creates a systemd service for auto-start
  • 👤 Adds a system user mailpit
  • 🛠️ Supports uninstall
  • 🔁 Enables and starts Mailpit on boot

🔧 Requirements​

  • 🐧 Linux (x86_64 / arm64 / 386) or 🍏 macOS
  • curl, tar
  • jq, awk, or sed (for parsing GitHub API)
  • systemd (for service support)

⚙️ Installation Options​

🆾️ OPTION 1: Default (Quick Install)​

Installs Mailpit with default ports and binary path.

curl -sSL https://raw.githubusercontent.com/asifkhan03/mailpit-setup/main/mailpit-install.sh | sudo bash
  • 🔧 Installs to: /usr/local/bin
  • 🌐 Web UI: http://localhost:8025
  • 📬 SMTP: localhost:1025

🆾️ OPTION 2: Custom Install (Download & Run Manually)​

Step 1: Download the script

curl -O https://raw.githubusercontent.com/asifkhan03/mailpit-setup/main/mailpit-install.sh
chmod +x mailpit-install.sh

Step 2: Run with custom values

➔ Custom ports​

MAILPIT_UI_PORT=8080 MAILPIT_SMTP_PORT=2525 sudo ./mailpit-install.sh

➔ Custom install path​

sudo ./mailpit-install.sh --install-path /opt/mailpit

➔ Use GitHub token for higher API limit​

GITHUB_TOKEN=ghp_your_token sudo ./mailpit-install.sh

➔ Uninstall​

sudo ./mailpit-install.sh --uninstall

🛠️ Service Commands​

# Check status
systemctl status mailpit

# Restart Mailpit
sudo systemctl restart mailpit

# View logs
journalctl -u mailpit -f

🔐 Environment Variables​

VariableDefaultDescription
MAILPIT_UI_PORT8025Port for the Web UI
MAILPIT_SMTP_PORT1025Port for the SMTP listener
GITHUB_TOKEN(none)GitHub token for rate-limit bypass

❓ What is Mailpit?​

Mailpit is a tool to:

  • ✉️ Intercept and display SMTP messages (great for dev/staging)
  • 🧱 Offer a simple Web UI to browse emails
  • ❌ Avoid accidentally sending real emails during development

GitHub: axllent/mailpit

📬 Testing Mailpit with CLI and Python

Once you've installed and started Mailpit (via mailpit-setup), here’s how you can test if it's working correctly.

Mailpit listens by default:

✅ Option 1: Test using sendemail command-line tool​

🔹 Step 1: Install sendemail​

sudo apt update
sudo apt install sendemail libio-socket-ssl-perl libnet-ssleay-perl -y

🔹 Step 2: Send a test email​

sendemail -f [email protected] \
          -t [email protected] \
          -u "Mailpit Test Email" \
          -m "This is a test email sent via sendemail on port 1025." \
          -s localhost:1025

✅ Now check Mailpit UI at http://localhost:8025 — you’ll see the test email there.

🐍 Option 2: Test using a Python script​

🔹 Step 1: Create a script named test_mail.py​

# test_mail.py
import smtplib
from email.mime.text import MIMEText

msg = MIMEText("This is a test email from Python to Mailpit")
msg['Subject'] = "Python → Mailpit"
msg['From'] = "[email protected]"
msg['To'] = "[email protected]"

with smtplib.SMTP("localhost", 1025) as server:
    server.send_message(msg)

print("✅ Mail sent!")

🔹 Step 2: Run it​

python3 test_mail.py

🧠 Then check: http://localhost:8025

🧪 Pro Tip: Testing with HTML or attachments​

Want to test HTML or attachments via Mailpit? Let me know and I’ll give you an example script.

🔍 Troubleshooting​

  • Make sure Mailpit is running:

    systemctl status mailpit

  • If you're using a remote server, open ports 8025 and 1025 in your firewall or security group.

Made with ❤️ by Asif Ahmad Khan

📄 License​

MIT © Asif Ahmad Khan 👨‍💻