E-MailRelay User Guide

What is it?

E-MailRelay is a simple store-and-forward message transfer agent and proxy server. It runs on Unix-like operating systems (including Linux), and on Windows.

When used as proxy server the E-MailRelay program (emailrelay) runs in the background and accepts e-mail from local e-mail client programs (KMail, Outlook etc.) or from the outside world, using the SMTP protocol. As soon as an e-mail message is received it is forwarded on to the next SMTP server for onward delivery. This becomes more useful when you add in your own message processing: as each message is received it can be passed one of your programs for editing, filtering, encrypting etc.

When used as a store-and-forward transfer agent E-MailRelay runs in two modes: the storage daemon part, and the forwarding agent. The storage daemon waits for incoming mail and stores anything it receives in a spool directory. As a forwarding agent E-MailRelay pulls messages out of the spool directory and passes them on to a remote server -- perhaps your ISP mail server.

E-MailRelay can also run as a POP3 server so that e-mail client programs can read the spooled messages.

What it's not

E-MailRelay is not a routing MTA. It forwards e-mail to a pre-configured SMTP server, regardless of any message addressing or DNS redirects.

E-MailRelay is not a delivery agent. Some programs like fetchmail send locally-addressed e-mail to the local SMTP server in order to deliver them to local system mailboxes. E-MailRelay will not normally do this.

Why use it?

E-MailRelay is a simple tool that does SMTP. For simple tasks it is likely to be easier to understand and configure than a more general purpose MTA.

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.

It has no dependencies on third-party libraries or run-time environments so it is easy to build and install, and the single-threaded, event-driven design with non-blocking i/o may provide better performance and resource usage than some of the alternatives.

Typical applications of E-MailRelay include:

Running E-MailRelay

To use E-MailRelay in store-and-forward mode use the --as-server switch to start the storage daemon in the background, and then trigger delivery of spooled messages by running with the --as-client switch and the address of the target host.

For example, to start a storage daemon listening on port 10025 use a command like this:

emailrelay --as-server --port 10025 --spool-dir /tmp

And then to forward the spooled mail to smarthost run something like this:

emailrelay --as-client smarthost:smtp --spool-dir /tmp

To get behaviour more like a proxy you can add the --poll switch so that messages are forwarded continuously rather than on-demand. This example starts a store-and-forward server that forwards spooled-up e-mail every hour:

emailrelay --as-server --poll 3600 --forward-to smarthost:smtp

For a proxy server that forwards each message as it is being received, without any delay, you can use the --as-proxy mode:

emailrelay --as-proxy smarthost:smtp

If you want to edit or filter e-mail as it passes through the proxy then specify your pre-processor program with the --filter switch, something like this:

emailrelay --as-proxy smarthost:smtp --filter /usr/local/bin/addsig

To run E-MailRelay as a POP server without SMTP use --pop and --no-smtp:

emailrelay --pop --no-smtp --log --close-stderr

The emailrelay-submit utility can be used to put messages straight into the spool directory so that the POP clients can fetch them.

Note that by default E-MailRelay will always reject connections from remote machines. To allow connections from anywhere use the --remote-clients switch, but please consider the implications if your machine is connected to the internet.

For more information on the command-line options refer to the reference guide or run:

emailrelay --help --verbose


The emailrelay program itself is mostly configured through command-line switches (such as --port and --forward-to), so there is no single definitive configuration file.

However, in most installations on Unix-like system the E-MailRelay server will be started up by the boot-time script called emailrelay in the /etc/init.d directory, and this script uses the configuration file /etc/emailrelay.conf to define the server command-line. Each entry in the configuration file corresponds to an E-MailRelay command-line switch, so you can edit this file to add and remove server switches. Refer to the reference guide for a complete list of configuration switches.

On Windows the installation program creates a startup batch file called emailrelay-start.bat that contains all the server command-line switches and you can edit this file to tailor the server configuration. You can also set up your own shortcuts to the E-MailRelay executable and add and remove command-line switches using the shortcut properties tab.

If you are using authentication then you will have to create the text files containing your authentication secrets (passwords and password hashes). The --server-auth, --client-auth and --pop-auth command-line switches are used to point to these files.

There is also a graphical configuration program called emailrelay-gui that may be available to help with configuring the system. This is intended to be used once at installation time (and it is the basis of the self-extracting installer on Windows) but it may also be used to do some simple reconfiguration of an alreay-installed system.


If the --log switch is used then E-MailRelay program issues warnings and error messages to the syslog system using the LOG_MAIL facility. Under Windows it writes to the Application event log.

The syslog system is configured through the /etc/syslog.conf file (try man syslog.conf), and in most cases you will find that LOG_MAIL warnings and errors are directed to an appropriate log file (perhaps /var/log/messages).

For more verbose logging add the --verbose switch. If this becomes difficult to read via the system log (especially on Windows) then try logging to the standard error stream and redirect that to a file. Bear in mind that you will need have to replace --as-server with --log and --as-proxy with --immediate --forward-to since the --as-server and --as-proxy switches implicitly close the standard error stream soon after startup.

emailrelay --log --verbose > emailrelay.log 2>&1


A useful technique for troubleshooting SMTP problems is to telnet into the remote server and drive the SMTP protocol manually. Telnet can be told to connect to the remote SMTP port by putting the port number (25) on the command line after the remote hostname, for example: telnet smtp.myisp.net 25.

Once connected you should get a startup banner from the server, which may tell you what server software you have connected to. From there you should type something like EHLO myhost.mydomain. The response to the EHLO command should contain a list of SMTP extensions which the server software supports. If this includes the AUTH extension then the set of supported authentication mechanisms (such as LOGIN, CRAM-MD5 etc.) will be listed on the same line.

After the EHLO response you should type MAIL FROM:<myhost.mydomain>, retaining the angle brackets but substituting your own address. If this is accepted then enter a RCPT TO:<me@myhost.mydomain> command to say where the e-mail is going. (Again, retain the angle brackets but substitute an appropriate address.)

After one or more RCPT TO commands you should enter the DATA command, followed by the message content. The message content should include an RFC822 header, followed by a blank line, followed by the message text. For testing purposes you might get away without having any header/body structure at all, but to do things properly you should have at least a To: line, a From: line and a Subject: line in the header.

At the end of the message text type a . on a line of its own. At that point the message should get dispatched, and eventually end up in your in-box in the usual way (assuming you put your own address in the RCPT TO command).

The following is an example SMTP dialogue, with >> and << marks added to show what was typed and what was received:

>> telnet smtp.myisp.net 25
<< Trying
<< Connected to smtp.myisp.net.
<< Escape character is '^]'.
<< 220 mail12.myisp.net ESMTP Exim 3.13 #0 Sat, 17 Nov 2001 16:22:39 +0000
>> EHLO myhost.myisp.net
<< 250-mail12.myisp.net Hello modem-185.myisp.net []
<< 250-SIZE 104857600
<< 250 HELP
>> MAIL FROM:<me@myhost.myisp.net>
<< 250 <me@myhost.myisp.net> is syntactically correct
>> RCPT TO:<me@myhost.myisp.net>
<< 250 <me@myhost.myisp.net> verified
<< 354 Enter message, ending with "." on a line by itself
>> To: me@myhost.myisp.net
>> From: me@myhost.myisp.net
>> Subject: test
>> Test message.
>> .
<< 250 OK id=1658Fp-0000Il-00
<< 221 mail12.myisp.net closing connection
<< Connection closed by foreign host.

If you get some sort of access denied errors when talking to a server which does not support the AUTH extension, then your ISP may be using POP-before-SMTP authentication. In this scheme you are required to conduct an authenticated POP or IMAP dialogue before you try to use SMTP. The POP/IMAP dialogue is done separately from the SMTP connection, but bear in mind that there might be a time limit so that your SMTP connection has to be made soon after the POP/IMAP authentication. You should be able to use an e-mail client program, or something like fetchmail to do the POP/IMAP authentication.

If you can send mail messages sucessfully using telnet, then you should look at the E-MailRelay --verbose log output and compare what you do interactively with what the program does.

Preventing open mail relay

If you are running E-MailRelay as a server with a permanent connection to the Internet it is important to prevent open mail relay because this can be exploited by spammers. By default open mail relaying is not possible because E-MailRelay does not accept IP connections from remote clients. However, if you use the --remote-clients switch then you need to be more careful.

If the only required access to the E-MailRelay server is from a local network and not from the Internet then you can use the --interface switch to listen for incoming connections only on the local network interface. You should also use a firewall in this scenario.

Another option is to require all clients to authenticate by using the --server-auth switch. If you then need local clients, such as your own e-mail client program, to connect without authentication then you must put those trusted IP addresses in the secrets file with an authentication mechanism of NONE. Refer to the reference guide for more information.

Taking it one stage further, you may want to allow connections from the Internet without authentication but only allow them to send mail to local users. In other words you want to allow anyone to deliver e-mail to your system but not allow them to spam someone else. You can do this by requiring authentication with the --server-auth switch, then exempt everyone from mandatory authentication with NONE server *.*.*.* x line in the secrets file, and finally have an address verifier script (--verifier) which rejects remote recipient addresses if the client has not authenticated. Again, refer to the reference guide for further details.

Running as a POP server

E-MailRelay can run as a POP server so that e-mail client programs can retrieve messages from the spool directory directly (although it is not a good idea to run E-MailRelay as a POP server if also forwarding messages by SMTP).

To allow POP access to spooled messages use a command-line something like this:

emailrelay --as-server --pop --pop-auth /etc/emailrelay.auth

You will need to create the authentication secrets file (/etc/emailrelay.auth in this example) containing usernames and passwords. A simple example would look like this:

APOP server user1 password1
APOP server user2 password2

If you need to serve up messages to more than one POP client consider using the --pop-by-name option with a --filter script that moves messages into the appropriate sub-directory. The emailrelay-filter-copy program is designed to be used in this way: when a message is received over SMTP it copies it into all available sub-directories for collection by multiple POP clients.

Refer to the reference guide for more information.

Triggering delivery over dial-up

If you are using E-MailRelay to store and forward e-mail over a dial-up link to the Internet, then you will need to set things up so that the dialler tells E-MailRelay when to start forwarding.

In most Unix-like systems a ppp daemon calls the script /etc/ppp/ip-up when it has successfully established a dial-up link to your ISP. This script will probably set up IP routes, update the DNS configuration, initialise a firewall, run fetchmail and sendmail, etc. It may also call out to another script, ip-up.local which is available for you to put stuff into without having to edit ip-up itself.

The simplest approach for editing ip-up is to look for a sendmail -q line. If you find sendmail -q then it should be sufficient to replace it with this:

emailrelay --as-client <myisp>:smtp

where you substitute your ISP's SMTP server address for <myisp>.

Or if your ip-up calls out to ip-up.local then create a two-line /etc/ppp/ip-up.local script like this:

exec /usr/local/sbin/emailrelay --as-client <myisp>:smtp

If you create ip-up.local yourself remember to make it executable.

Notification of failed e-mails

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 failed e-mails to be retried a few times you can run the emailrelay-resubmit.sh script periodically, perhaps from cron. This script simply removes the .bad suffix from files in the spool directory, as long as they have not been retried too many times already.

If you are using E-MailRelay to forward outgoing e-mails then you can also get failed e-mails to bounce back to your in-tray by running the emailrelay-notify.sh script periodically as root, although this does require procmail to act as a delivery agent.

Polling and timeouts

In normal proxy mode, using --immediate or --as-proxy, the E-MailRelay server will try forward each message as soon as it is received and only then will it acknowledge receipt of the message back to the submitting client. This has the advantage that any problems with the forwarding process can be reported back to the submitting client; any failures should be reported your e-mail client program and the failed messages should stay in its outbox.

However, some e-mail client programs are not always prepared to wait long enough for the message to be forwarded and this can result in problems with timeouts. A good fix for this is to use the --poll mechanism as a replacement for --immediate/--as-proxy. In this way the submitting e-mail client program does not have to wait for the E-MailRelay server to forward each message and so it should not time out. If you have timeout problems try replacing --immediate with --poll 0 so that forwarding is done as soon as the client has finished submitting messages.

Usage patterns

The simplest ways of using E-MailRelay for SMTP are as a proxy or as a store-and-forward MTA, but many other configurations are possible. For example, multiple E-MailRelay servers can run in parallel sharing the same spool directory, or they can be chained in series to that e-mail messages get transferred from one to the next.

Remember that messages can be introduced directly into the E-MailRelay spool directory using the emailrelay-submit utility, and they can be moved out again at any time, as long as the envelope file is not locked (ie. with a special filename extension). Your --filter program can edit messages in any way you want, and it can even remove the current message from the spool directory.

When using E-MailRelay as a POP server the --pop-by-name feature can be used to serve up different spooled messages according to the username that the client authenticated with: each user's messages are taken from their own sub-directory of the main spool directory. If messages are coming in over SMTP then you could install an SMTP --filter script to move each new message into the relevant sub-directory based on the message addressing.

For more ideas check out the --client-filter and --poll switches, and don't overlook the administration and control interface (--admin) which you can use to receive notification of message arrival or force message forwarding at any time.


The E-MailRelay server can use SpamAssassin to mark or reject potential spam.

To get E-MailRelay to reject spam outright you can just use spamassassin -e as your E-MailRelay --filter program:

emailrelay --as-server --filter "/usr/bin/spamassassin --exit-code"

Or on Windows:

emailrelay --as-server --filter "c:/Program\ Files/perl/site/bin/spamassassin.bat --exit-code"

To get spam messages identified by SpamAssassin but still pass through the E-MailRelay system you will have to have a small --filter script to collect the output from the spamassassin program and write it back into the E-MailRelay content file.

Your --filter shell script could look something like this:

spamassassin "$1" > "$1.tmp"
mv "$1.tmp" "$1"
exit 0

Or an equivalent batch script on Windows:

c:\Program Files\perl\site\bin\spamassassin.bat %1 > %1.tmp
ren %1.tmp %1
exit 0

You may need to set the --filter-timeout switch to control how long E-MailRelay waits for the spam analysis to complete.

You could also consider doing spam filtering off-line, completely independent of any SMTP activity, by having two E-MailRelay processes chained together working off two spool directories:

emailrelay --as-server --spool-dir /tmp/spool-in --poll 1 --forward-to localhost:10025
emailrelay --as-server --spool-dir /tmp/spool-out --port 10025 --filter /tmp/myspamfilter

Here the first E-MailRelay server accepts incoming mail straight into its spool directory and it uses a --poll timer to independently forward spooled messages to the second server running on port 10025. The second server runs the spam filter as each message is received.

There is also an experimental mechanism where E-MailRelay can talk direcly to the SpamassAssin spamd network deamon using a special form of the --filter switch:

emailrelay --as-server --filter spam:localhost:783

This might be useful if spam filtering is creating a bottleneck in the E-MailRelay server.

Google mail

To send mail via Google mail's SMTP gateway you will need to create a client secrets file containing your account details and enable TLS support in E-MailRelay by using the --client-tls switch.

The secrets file should contain one line of text something like this:

login client myname@gmail.com mypassword

Reference this file using --client-auth on the E-MailRelay command-line and also add in the --client-tls switch:

emailrelay --as-proxy smtp.gmail.com:587 --client-tls --client-auth /etc/emailrelay.auth ...

Copyright (C) 2001-2008 Graeme Walker <graeme_walker@users.sourceforge.net>. All rights reserved.