smtp-loadbalancer/README.md

SMTP Load Balancer

Easily distribute emails across multiple upstream SMTP providers

About • Prerequisites • Installation • Usage • License

About

SMTP Load Balancer is a powerful tool designed to distribute emails across multiple upstream SMTP providers, ensuring high availability, reliability and scalability.

Prerequisites

To use SMTP Load Balancer, you'll need:

• One or more SMTP email providers

For deployment:

• Docker & Docker Compose (Recommended)
• OR Node.js 24+

Installation

Using Docker (Recommended)

1. Create a directory for your configuration:

   mkdir smtp-loadbalancer && cd smtp-loadbalancer
   

2. Download the example configuration and docker-compose file:

   curl -O https://raw.githubusercontent.com/ovosimpatico/smtp-loadbalancer/main/config.example.json
   curl -O https://raw.githubusercontent.com/ovosimpatico/smtp-loadbalancer/main/docker-compose.yml
   

3. Create your config.json file:

   cp config.example.json config.json
   nano config.json
   

4. Run the application:

   docker compose up -d
   

5. The SMTP server will be listening on port 2525.

Native Node.js Installation

1. Clone the repository and enter the directory:

   git clone https://github.com/ovosimpatico/smtp-loadbalancer.git
   cd smtp-loadbalancer
   

2. Install dependencies:

   npm install
   

3. Make your config.json file based on the example file

   cp config.example.json config.json
   nano config.json
   

4. Run the server:

   npm start
   

5. The SMTP server will be listening on port 2525.

Usage

The software will be listening on port 2525 and will be accepting emails.

To send emails, you can use:

SMTP-compatible email clients:

• Thunderbird
• Microsoft Outlook
• Evolution
• K-9 Mail
• mail CLI

SMTP libraries for programming languages:

• Node.js (nodemailer)
• Python (smtplib)
• PHP (PHPMailer)
• C# (MailKit)
• Go (net/smtp)

Or, you may integrate it with your self-hosted services, like Nextcloud or Forgejo.

Once integrated, you can use the SMTP Load Balancer as your primary email server.

Note: Since the FROM address will already be set for each provider, the FROM field on your sent emails will be rewritten to the REPLY-TO address, to ensure replies are sent to the correct address.

License

This project is licensed under the GNU Affero General Public License v3.0 (AGPLv3). This means that you are free to use, modify and distribute the software, so as long as you release the source code of your fork to all users, even when interacting with it over a network.

See the LICENSE file for details.

Disclaimer

This project is not affiliated with any email service provider, and it's not a replacement for a dedicated email server, but rather a relay server for outgoing email services.

This project is not intended to be used to circumvent or abuse any email service provider's policies or to send spam.

This tool is provided "as is", without any warranty. Use at your own risk. By using it, you agree and respect the terms of the AGPLv3 License and all terms of service of the email service providers you use.