********** User Guide ********** What is it? =========== E-MailRelay is a lightweight `SMTP`_ store-and-forward mail server with `POP`_ access to spooled messages. Store-and-forward operation is normally to a fixed smarthost but e-mail routing using DNS MX lookups can also be configured. It can be used as a personal internet mail server using SpamAssassin spam filtering and `DNSBL`_ connection blocking, with incoming e-mail delivered to `maildir`_ mailboxes. External scripts can be used for address validation and for processing e-mail messages as they are received. .. image:: whatisit.png :target: whatisit.svg E-MailRelay runs as a single process using the same non-blocking i/o model as Squid and nginx giving excellent scalability and resource usage. The code has few dependencies on third-party libraries or run-time environments so it is easy to build and install. E-MailRelay is designed to be policy-free, so that you can implement your own policies for message retries, bounces, local mailbox delivery, spam filtering etc. through external scripts. .. image:: download-button.png :target: https://sourceforge.net/projects/emailrelay/files/latest/download Basic operation =============== E-MailRelay can be run straight from the command-line, and on Windows you can run *emailrelay.exe* or *emailrelay-textmode.exe* from the zip file without going through the installation process. To use E-MailRelay in store-and-forward mode use the :option:`--as-server` option to start the storage daemon in the background, and then do delivery of spooled messages by running with :option:`--as-client`. .. image:: serverclient.png :target: serverclient.svg For example, to start a storage daemon in the background listening on port 10025 use a command like this: :: emailrelay --as-server --port 10025 --spool-dir /tmp On Windows use *c:/temp* for testing, rather than */tmp*. Or to run it in the foreground: :: emailrelay --log --no-daemon --port 10025 --spool-dir /tmp And then to forward the spooled mail to *smtp.example.com* run something like this: :: emailrelay --as-client smtp.example.com:25 --spool-dir /tmp To forward continuously you can add the :option:`--poll` and :option:`--forward-to` options to the server command-line: .. image:: forwardto.png :target: forwardto.svg For example, this starts a server that also forwards spooled-up e-mail every minute: :: emailrelay --as-server --poll 60 --forward-to smtp.example.com:25 Or for a server that forwards each message as soon as it has been received, you can use :option:`--forward-on-disconnect`: :: emailrelay --as-server --forward-on-disconnect --forward-to smtp.example.com:25 To edit or filter e-mail as it passes through the server specify your filter program with the :option:`--filter` option, something like this: :: emailrelay --as-server --filter /tmp/set-from.js Look for example filter scripts in the *examples* directory. E-MailRelay can also be used as a personal internet mail server: .. image:: mailserver.png :target: mailserver.svg Use :option:`--remote-clients` (*-r*) to allow connections from outside the local network, define your domain name with :option:`--domain` and use an address verifier as a first line of defense against spammers: :: emailrelay --as-server -v -r --domain=example.com --address-verifier=account: Then enable `POP`_ access to the incoming e-mails with :option:`--pop`, :option:`--pop-port` and :option:`--pop-auth`: :: emailrelay ... --pop --pop-port 10110 --pop-auth /etc/emailrelay.auth Set up the POP account with a user-id and password in the :option:`--pop-auth` secrets file. The secrets file should contain a single line of text like this: :: server plain For more information on the command-line options refer to the reference guide or run: :: emailrelay --help --verbose Configuration ============= After a full installation the E-MailRelay server will normally be started up automatically when the machine boots up. On Unix-like systems the server will read its configuration settings from a file */etc/emailrelay.conf*. On Windows E-MailRelay typically runs as a Windows Service and it reads its configuration from the startup batch file *emailrelay-start.bat* and/or the configuration file *emailrelay.cfg* in the *ProgramData/E-MailRelay* folder. (If you can't find this folder look for the *E-MailRelay* link in the *Program Files/E-MailRelay* folder and then right-click and "open file location".) You can change the E-MailRelay server configuration by editing the configuration file or startup batch file directly and then restarting the server. Or you can use the E-MailRelay configuration GUI if it is available. In many cases E-MailRelay will need to be configured with user-ids and passwords. For example, if e-mail is being forwarded to a *smarthost* for onward routing then you will need to supply the user-id and password for your account on the smarthost. These details must be entered into a *secrets* file and then one of :option:`--server-auth`, :option:`--client-auth` or :option:`--pop-auth` must be used to point to the file. The E-MailRelay reference document describes the format of the secrets file. Logging ======= E-MailRelay is normally installed so that it logs its activity to a log file, but it can also send logging information to *syslog* on Unix systems or the to the Event Viewer on Windows. Logging is configured with options like :option:`--log`, :option:`--log-file`, :option:`--as-server` and :option:`--syslog`, so check these in the configuration file and/or startup batch file. For more verbose logging add the :option:`--verbose` option. This is a good idea when setting up or trouble-shooting your E-MailRelay configuration. Failures and retries ==================== If e-mail messages cannot be forwarded by the E-MailRelay system then the envelope files in the spool directory are given a *.bad* suffix. The reason for the failure will be recorded in the envelope file itself. You should check for *.bad* envelope files in the E-MailRelay spool directory from time to time. If you want a failed message to be retried then just remove the *.bad* filename suffix from the envelope. Use regular polling (e.g. :option:`--poll` *60*) to make sure that renamed messages get picked up and forwarded in a timely manner. To retry failed messages automatically run a script periodically that renames the *.bad* envelope files. A convenient way to run a retry script is to use the :option:`--poll-run` option with :option:`--poll`: :: emailrelay --as-client example.com:25 --poll 60 --poll-run @app/retry ... Even easier is to use the built-in script called :ref:`builtin_retry`, which will remove the *.bad* filename suffix from an envelope file for up to five retries or until the remote server rejects it with a 5xx response. :: emailrelay --as-client example.com:25 --poll 60 --poll-run retry: ... The retry cycle can be made independent of forwarding by using a separate section in the configuration file, introduced with a *spool-dir* line having an arbitrary prefix (here *retry*) and combined with *dont-serve*: :: retry-spool-dir /var/spool/emailrelay retry-dont-serve retry-poll 1h retry-poll-run retry: Open mail servers ================= If you are running E-MailRelay as an internet mail server then you need to be careful about abuse by spammers and bot-nets. You will also need to be sure that incoming e-mail messages are never automatically routed back out to the internet because that will definitely attract abuse. By default an E-MailRelay server will only accept connections from local network addresses, so for an internet mail server you will need to add the :option:`--remote-clients` option. When you add :option:`--remote-clients` you should be sure that you have a firewall that blocks connections to any other ports that E-MailRelay might have open, or use the :option:`--interface` option to limit their scope. A good first step in limiting abuse is to use an address verifier that checks that e-mails are correctly addressed to you. You can use the built-in address verifier called :ref:`builtin_account` to do this or you can write your own verifier script. :: emailrelay --as-server --remote-clients --address-verifier=account: --domain=mydomain.com Refer to the *Address verifiers* section in the E-MailRelay reference document for more details. If you want to run an internet mail server that is not open to everyone then you can require that remote users authenticate themselves. Do this with a secrets file containing a user-id and password for every remote user, something like this: :: server plain user1 password1 server plain user2 password2 And then use :option:`--server-auth` to point to the file: :: emailrelay --as-server --remote-clients --server-auth=/etc/emailrelay.auth Refer to the *Authentication* section in the E-MailRelay reference document for more details. Running as a POP server ======================= E-MailRelay can run as a `POP`_ server so that an e-mail client program can retrieve messages from the E-MailRelay spool directory. To allow POP access use the :option:`--pop` and :option:`--pop-auth` command-line options, something like this: :: emailrelay --as-server --pop --pop-auth=/etc/pop.auth You will need to create the :option:`--pop-auth` secrets file. It should contain one line of text that gives the username and password that your e-mail client will use when connecting to E-MailRelay, for example: :: server plain user1 password1 If you are using POP to view a spool directory that is also being used for e-mail forwarding then you should use :option:`--pop-no-delete`. If using more than one e-mail client program then you might want to make independent copies of your e-mails for each client. Use a :option:`--filter` program to copy the e-mail files into sub-directories of the main spool directory and then use :option:`--pop-by-name` so that each e-mail client accesses its own sub-directory according to which account name it used when authenticating. The filter can be an external program, or just use the built-in :ref:`builtin_copy` filter. .. image:: popbyname.png :target: popbyname.svg IMAP ==== E-MailRelay does not support the `IMAP`_ protocol directly but a simple filter script can be used to move e-mails into a `maildir`_ directory and an IMAP server such as `dovecot`_ can be used to serve them from there. It is normally sufficient for a filter script to just move the E-MailRelay content file straight into the mailbox *cur* directory, delete the corresponding envelope file and then exit with an exit code of 100. The built-in :ref:`builtin_deliver` filter can be used to do this. Forwarding on demand ==================== If you are using E-MailRelay on a Linux/Unix system to store and forward e-mail over an intermittent link to the internet such as dial-up or wireless networking, then you might need to arrange for E-MailRelay to be notified when it can start forwarding e-mail. You should find that there are special directories where you can install your own hook scripts that are called whenever a dial-up or wireless network connection is established. For dial-up this might be */etc/ppp/ip-up.d*, and for wireless */etc/network/if-up.d*. Just create a two-line script like this in the relevant directory: :: #!/bin/sh echo forward | /usr/bin/nc -q 1 -w 1 127.0.0.1 10026 > /dev/null Make the script executable using *chmod +x* and install *netcat* if necessary. Then enable the E-MailRelay admin interface on port 10026 with these lines in the configuration file: :: admin 10026 interface admin=127.0.0.1 Rate limiting ============= If you need to slow the rate at which e-mails are forwarded you can use a :option:`--client-filter` program to introduce a delay. On Windows this `JavaScript`_ filter program would give you a delay of a minute: :: WScript.Sleep( 60000 ) ; WScript.Quit( 0 ) ; However, this can cause timeouts at the server, so a better approach is to use :option:`--client-filter` *exit:102* so that only one e-mail message is forwarded on each polling cycle, and then use :option:`--poll` *60* to limit it to one e-mail per minute. SpamAssassin ============ The E-MailRelay server can use `SpamAssassin `_ to mark or reject potential spam. It's easiest to run SpamAssassin's *spamd* program in the background and let E-MailRelay send incoming messages to it over the local network. The built-in :ref:`builtin_spam-edit` filter is used to pass e-mail messages to spamd, which normally listens on port 783: :: emailrelay --as-server --filter=spam-edit:127.0.0.1:783 If SpamAssassin detects a message is spam it will edit it into a spam report with the original e-mail moved into an attachment. Alternatively use the :ref:`builtin_spam` filter if spam e-mails should be rejected outright: :: emailrelay --as-server --filter=spam:127.0.0.1:783 Google mail =========== To send mail via Google mail's `SMTP`_ gateway you will need to obtain a new *application password* from Google: log in to your Google account and look for the account's security settings and then *app passwords*. Create the password for E-MailRelay selecting an application type *other*. Then create a client secrets file for E-MailRelay containing your account name and the new application password. You may already have this file on Windows as *C:\\ProgramData\\E-MailRelay\\emailrelay.auth*. You should edit the secrets file to contain one *client* line, something like this: :: client plain myname@gmail.com myapppassword Then change the E-MailRelay configuration file to refer to your secrets file by using the :option:`--client-auth` option. Also set the :option:`--as-proxy` or :option:`--forward-to` option to *smtp.gmail.com:587* and add :option:`--client-tls` to enable `TLS`_ encryption. On Windows your settings might look something like this in the *emailrelay.cfg* configuration file: :: forward-to smtp.gmail.com:587 client-tls client-auth C:/ProgramData/E-MailRelay/emailrelay.auth Or in the Windows startup batch file (*emailrelay-start.bat*) these settings should all go on one line: :: start ... emailrelay --as-proxy=smtp.gmail.com:587 --client-tls --client-auth=C:/ProgramData/E-MailRelay/emailrelay.auth ... Microsoft 365 ============= E-MailRelay can forward e-mails to a Microsoft 365 Exchange server for onward delivery. Set the :option:`--forward-to` address to *smtp.office365.com:587*, and enable authentication and `TLS`_ by using the :option:`--client-auth` and :option:`--client-tls` options, or add these lines to the *emailrelay.cfg* configuration file: :: forward-to smtp.office365.com:587 client-tls client-auth C:/ProgramData/E-MailRelay/emailrelay.auth The secrets file (*emailrelay.auth*) should contain the credentials for logging in to the Microsoft server, but because Microsoft's policy is to limit the use of passwords these credentials will normally have to be `OAUTH`_ tokens: :: client oauth:b me@mydomain.onmicrosoft.com dXNlcj1ncmFlbWVAZ3JhZW1ld2Fsa2VyLm9ub... Configure your Microsoft 365 `Exchange `_ server's 'mail flow' to allow `SMTP`_ AUTH and register E-MailRelay as an authenticating application, and then obtain a fresh OAUTH token to go into the E-MailRelay secrets file before forwarding e-mails. Use the `scripts `_ on GitHub from DATA-Systems GmbH to help with this. You will need to edit the update script to set your application id etc. Connection tunnelling ===================== E-MailRelay can send mail out via a `SOCKS`_ v4 proxy, which makes it easy to route your mail through an encrypted tunnel created by *ssh -N -D* or via the Tor anonymising network. For example, this will run an E-MailRelay proxy on port 587 that routes via a local Tor server on port 9050 to the mail server at smtp.example.com: :: emailrelay --port 587 --as-proxy=smtp.example.com:25@localhost:9050 --domain=anon.net --anonymous --connection-timeout=300 Blocklists and dynamic firewalls ================================ E-MailRelay can consult with remote `DNSBL`_ blocklist servers in order to block incoming connections from known spammers. For example: :: emailrelay -r --dnsbl=zen.spamhaus.org,bl.mailspike.net ... Refer to the documentation of the :option:`--dnsbl` option for more details. It is also possible to integrate E-MailRelay with intrusion detection systems such as *fail2ban* that monitor log files and dynamically modify your iptables firewall. Use E-MailRelay's :option:`--log-format` *address* command-line option so that the remote IP addresses are logged and made visible to *fail2ban*. Bcc handling ============ E-MailRelay transfers e-mail messages without changing their content in any way, other than by adding a *Received* header. In particular, if a message contains a *Bcc:* header when it is submitted to the E-MailRelay server it will have the same *Bcc:* header when forwarded. It is normally the responsibility of the program that submits an e-mail message to submit it separately for each `BCC`_ recipient, removing the *Bcc:* header from the message content or changing it to contain only the 'current' recipient. If this is not done, perhaps through misconfiguration of the e-mail user agent program, then BCC recipients may be visible to the *To* and *Cc* message recipients. An E-MailRelay :option:`--filter` script can be used to reject messages with incorrect *Bcc:* headers, and an example script is included. Advanced set-up =============== As an example of an advanced E-MailRelay setup consider the following command-line, split onto multiple lines for readability: :: emailrelay --log --verbose --log-time --log-format=unit,network --close-stderr --syslog --pid-file @app/emailrelay.pid --user root --in-spool-dir @app/in --in-port 25 --in-domain example.com --in-address-verifier account: --in-dnsbl dnsbl.example.com --in-filter spam-edit:127.0.0.1:783 --in-filter deliver: --in-server-smtp-config +chunking,+smtputf8 --in-size 100000000 --in-pop --in-pop-port 110 --in-pop-auth pam: --in-pop-by-name --out-spool-dir @app/out --out-port 587 --out-forward-on-disconnect --out-forward-to-some --out-poll 60 --out-address-verifier account:check --out-delivery-dir @app/in --out-filter msgid: --out-filter deliver: --out-filter split: --out-client-filter mx: --out-forward-to 127.0.0.1:588 --out-domain example.com --out-poll-run retry:5 --other-spool-dir @app/other --other-port 588 --other-interface 127.0.0.1 --other-client-tls --other-client-auth plain:YWxpY2VAZ21haWwuY29t:UGFzc3cwcmQ --other-forward-to smtp.gmail.com:587 --other-poll 3600 This is a three-in-one configuration so there are effectively three E-MailRelay servers running in one process, named *in*, *out* and *other*. The *in* server is an internet-facing e-mail server with delivery to individual mailboxes that can be accessed via `POP`_. The :ref:`builtin_account` verifier checks the addressees in the incoming e-mails against the list of accounts on the local machine and against the given domain name; the IP address of the network connection is checked against a `DNSBL`_ database; SpamAssassin is used to identify spam; and Linux `PAM`_ is used for POP authentication. The *out* server is a routing `MTA`_ that sends outgoing e-mail messages directly to destination servers. The filter makes copies as necessary so that each e-mail message goes to just one domain. The client filter uses DNS MX queries against the local system's default name servers to do the routing. If any e-mail messages are addressed to local users they are short-circuited and delivered directly to their *in* mailboxes. Failed messages are retried up to five times. The *other* server does store-and-forward to a gmail smarthost and acts as the default destination for the *out* server. In this example the gmail password is given directly on the command-line but it is normally more secure to use a separate secrets file. .. footer:: Copyright (c) 2026 Graeme Walker Copying and distribution of this file, with or without modification, are permitted in any medium without royalty provided the copyright notice and this notice are preserved. This file is offered as-is, without any warranty. .. _BCC: https://en.wikipedia.org/wiki/Blind_carbon_copy .. _DNSBL: https://en.wikipedia.org/wiki/DNSBL .. _IMAP: https://en.wikipedia.org/wiki/Internet_Message_Access_Protocol .. _JavaScript: https://en.wikipedia.org/wiki/JScript .. _MTA: https://en.wikipedia.org/wiki/Message_transfer_agent .. _OAUTH: https://www.microsoft.com/en-us/security/business/security-101/what-is-oauth .. _PAM: https://en.wikipedia.org/wiki/Linux_PAM .. _POP: https://en.wikipedia.org/wiki/Post_Office_Protocol .. _SMTP: https://en.wikipedia.org/wiki/Simple_Mail_Transfer_Protocol .. _SOCKS: https://en.wikipedia.org/wiki/SOCKS .. _TLS: https://en.wikipedia.org/wiki/Transport_Layer_Security .. _dovecot: https://www.dovecot.org .. _maildir: https://en.wikipedia.org/wiki/Maildir