******* 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* folder 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. Use the *nouac* batch file to run without administrator privileges. Note that you can run the main E-MailRelay program *emailrelay.exe* (or *emailrelay-textmode.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 folder 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 configuration 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 folder *C:\\Program Files\\E-MailRelay*. * Create a new spool folder *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, e.g. *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 selected with a check-box on the *Server startup* page in the installation program (*emailrelay-setup*) or later using the *emailrelay-gui* configuration program. The E-MailRelay installation program registers a service wrapper program called *emailrelay-service.exe* as the service executable and it is this that runs the main E-MailRelay server program. (Other service wrappers are available.) If not using the installation program then the E-MailRelay service wrapper can be set up manually. You must first have a configuration file called *emailrelay.cfg* that contains all the configuration options for running the E-MailRelay server. You must also have a one-line configuration file for the service wrapper called *emailrelay-service.cfg* and this must be in the same folder as the service wrapper executable. The contents of the service-wrapper configuration file should be a single line that points to the folder containing the main E-MailRelay configuration file (*emailrelay.cfg*), like this: :: dir-config="C:\ProgramData\E-MailRelay" Then just run *emailrelay-service --install* from an Administrator command prompt to install the service. For tighter security run the service under a *virtual service account*, either by using the *Services* tool's *Log On* tab or with the *sc config* command run from an administrator command prompt: :: sc config emailrelay obj= "NT Service\emailrelay" If you need to run multiple E-MailRelay services then put a unique service name and display name on the *emailrelay-service --install \ \* command-line. The service name you give is used to derive the name of the configuration file (*\.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. For any other error code first make sure that the configuration file is correct by running the startup batch file *emailrelay-start.bat* or run *emailrelay-textmode emailrelay.cfg* from a command prompt. For low-level diagnostic logging of the service wrapper set the path of a log file in the registry at *HKLM/SOFTWARE/emailrelay-service/logfile*. 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 (e.g. *C:\\Program Files\\E-MailRelay*). * Delete the files from the E-MailRelay *program data* folder (e.g. *C:\\ProgramData\\E-MailRelay*). * Delete any desktop shortcuts (e.g. *%USERPROFILE%\\Desktop\\E-MailRelay.lnk*). * Delete any start menu shortcuts (e.g. *%APPDATA%\\Microsoft\\Windows\\Start Menu\\Programs\\E-MailRelay.lnk*). * Delete any auto-start shortcuts (e.g. *%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 *Manage Optional Features* and enable the *Telnet client* checkbox under *More Windows Features*. 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:..*, *RCPT TO:..* and *DATA*. Refer to `RFC-821`_ Appendix F for some examples. .. 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. .. _RFC-821: https://tools.ietf.org/html/rfc821 .. _SMTP: https://en.wikipedia.org/wiki/Simple_Mail_Transfer_Protocol