E-MailRelay Windows
===================

Setup program
-------------
To install E-MailRelay on Windows run `emailrelay-setup.exe`.

The installation GUI will take you through the installation options and then
install the run-time files from the `payload` directory into your chosen
locations and also create a startup batch file (`emailrelay-start.bat`) and
configuration file (`emailrelay.cfg`).

If you plan to install into `Program Files` and `ProgramData`, or if you want
to run E-MailRelay as a Windows service then you will need to allow the
installation program to run as Administrator.

You can also run the main E-MailRelay program `emailrelay.exe` directly without
going through the installation process but you will need to refer to the
documentation to set the appropriate configuration options.

Running the program
-------------------
After a successful installation you should see E-MailRelay listed in the
Windows Start Menu and/or as an entry in the Windows `Services` tool.

The Start Menu item will run the startup batch file `emailrelay-start.bat`.
This is normally in the `ProgramData\E-MailRelay` folder, together with
the configuration file `emailrelay.cfg`. Once the E-MailRelay server is running
you should see an icon appear in the Windows System Notification Area (also
known as the System Tray) under the `Show hidden icons` button.

Or if E-MailRelay runs as a service you should see an entry in the Windows
`Services` tool with a status of Running. Check the E-MailRelay log file to see
what it is doing.

Configuration
-------------
E-MailRelay is configured with options like `--verbose` and `--spool-dir` in the
`emailrelay-startup.bat` batch file, or equivalently `verbose` and `spool-dir`
lines in the `emailrelay.cfg` configuration file.

Note that `emailrelay-start.bat` lives under `ProgramData`, and although this
might be a hidden directory you can still navigate there by right-clicking on
the E-MailRelay link under `Program Files\E-MailRelay` and selecting "Open file
location".

You can edit the batch file or configuration file using Notepad: right-click on
the file, then `show more options` and `edit`.

Alternatively, use the `emailrelay-gui` program to make the changes.

All configuration options are documented in the E-MailRelay reference document.

Account user-ids and passwords can be configured by editing the E-MailRelay
`secrets` file, normally `ProgramData\E-MailRelay\emailrelay.auth`. Check that
the `--client-auth` or `--server-auth` options in the startup batch file or
configuration file refer to this file.

Manual installation
-------------------
The manual installation process for when you cannot run the setup program can be
as simple as this:

* Create a new program directory `C:\Program Files\E-MailRelay`.
* Create a new spool directory `C:\Program Files\E-MailRelay\spool`.
* Copy the EXE files from `programs` in the zip file into `C:\Program Files\E-MailRelay`.
* Create a new text file, eg. `C:\Program Files\E-MailRelay\auth.txt`, to contain account details.
* Add account details to `auth.txt` with a line like `client plain myaccount mypassword`.
* Right-drag `emailrelay.exe` onto the desktop to create a shortcut for the server.
* Add configuration options to the server shortcut properties in the `target` box.

The configuration options should normally include:

* `--log`
* `--verbose`
* `--log-file=@app\log-%d.txt`
* `--spool-dir=@app\spool`
* `--client-auth=@app\auth.txt`
* `--client-tls`
* `--forward-to=smtp.example.com:25`
* `--forward-on-disconnect`
* `--poll=60`

Copy the shortcut to `Start Menu` and `Startup` folders as necessary.

Running as a service
--------------------
E-MailRelay can be set up as a Windows service so that it starts up
automatically at boot-time. This can be enabled on the `Server startup` page
in the installation program or later using the `emailrelay-gui` configuration
program.

Alternatively, to set up the service manually you must first have a
configuration file called `emailrelay.cfg` that contains all the configuration
options for running the E-MailRelay server, and you must have a simple
service-wrapper configuration file called `emailrelay-service.cfg` that points
to it, and this must be in the same directory as the service wrapper executable
(`emailrelay-service.exe`).

The contents of the service-wrapper configuration file can be a single line that
points to the folder containing the configuration file, like this:

        dir-config="C:\ProgramData\E-MailRelay"

Then just run `emailrelay-service --install` from an Administrator command
prompt to install the service.

If you need to run multiple E-MailRelay services then put a unique service
name and display name on the `emailrelay-service --install &lt;name&gt; &lt;display-name&gt;`
command-line. The service name you give is used to derive the name of the
configuration file (`&lt;name&gt;.cfg`) that contains the E-MailRelay server's
configuration options, so you will need to create that first.

Note that a `service specific` error code when starting the service is the main
`emailrelay` program's exit code. This will have the value 2 if the listening
socket is already in use, normally indicating that another E-MailRelay program
is running.

Uninstall
---------
To uninstall:

* Stop the program and/or the service.
* Uninstall the service, if installed (`emailrelay-service --remove`).
* Delete the files from the E-MailRelay `program files` folder (eg. `C:\Program Files\E-MailRelay`).
* Delete the files from the E-MailRelay `program data` folder (eg. `C:\ProgramData\E-MailRelay`).
* Delete any desktop shortcuts (eg. `%USERPROFILE%\Desktop\E-MailRelay.lnk`).
* Delete any start menu shortcuts (eg. `%APPDATA%\Microsoft\Windows\Start Menu\Programs\E-MailRelay.lnk`).
* Delete any auto-start shortcuts (eg. `%APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup\E-MailRelay.lnk`).
* Clean up the registry under `HKLM\System\CurrentControlSet\Services\EventLog\Application\emailrelay`.

Diagnostics
-----------
E-MailRelay logging is sent to the Windows Event Log and/or written to a log
file, and individual failed mail messages will have the failure reason recorded
inside the `.bad` envelope file.

The Windows Event Log can be accessed by running `eventvwr.exe` or searching for
`Event Viewer`; from there look under `Windows Logs` and `Application`.

You can increase the verbosity of the logging by adding the `--verbose` option
to the E-MailRelay options, typically by editing the `emailrelay.cfg`
configuration file in the `C:\ProgramData\E-MailRelay` folder.

Testing with telnet
-------------------
The `telnet` program can be used for testing an E-MailRelay server.

To install the program search for `Windows Features` and enable the "Telnet
client" checkbox.

Then run telnet from a command prompt, using `localhost` and the E-MailRelay
port number as command-line parameters:

        telnet localhost 25

This should show a greeting from the E-MailRelay server and then you can
start typing [SMTP][] commands like `EHLO`, `MAIL FROM:&lt;..&gt;`, `RCPT TO:&lt;...&gt;`
and `DATA`. Refer to [RFC-821][] Appendix F for some examples.





[RFC-821]: https://tools.ietf.org/html/rfc821
[SMTP]: https://en.wikipedia.org/wiki/Simple_Mail_Transfer_Protocol

_____________________________________
Copyright (C) 2001-2024 Graeme Walker
