Installation and Upgrade Using the EXE
SmarterMail comes as a single installation file that contains everything necessary to run the product and get it set up on your server, regardless of the Edition that you intend to use. The features available are based on the license used during the activation process; if no license is entered, the Free Version will be installed. SmarterMail installers are available on the SmarterMail Downloads page of our website.
See Windows Installation Via CLI for "silently" installing SmarterMail using a Command Line Interface (CLI)
Jump to:
- Installing SmarterMail Using the .EXE
- Upgrading SmarterMail
- Upgrade Process
- Things to Know
- Troubleshooting
- Upgrading Failover Servers
- Steps for Upgrading Legacy Versions
Installing SmarterMail Using the .EXE
Once you've downloaded the installation file from the SmarterTools website, it's time to actually install the product. SmarterMail starts by installing its mail service. This includes setting up all folders and directories needed to run SmarterMail. Therefore, it's just like any standard program installation:
- On the first page, you select the path for the installation and accept the license terms.
- Next, you'll input any licensing and activation information:
- Free Edition - Select this if you're going to test out SmarterMail. The Free Edition is essentially SmarterMail Enterprise (with some limitations) and works for a single domain and up to 10 email accounts.
- Enter a license key - If you have purchased SmarterMail, select this: you'll then be prompted to enter the license key so the product can be activated.
- Manual activation provided by support - In some systems, those locked behind strict network security policies for example, SmarterMail is used for internal purposes only. In these cases a "manual activation" of the product is necessary. These are provided by the SmarterTools support team.
- Once the activation information is provided, you'll see an overview of the SmarterMail version and mailbox allocation.
- Next, you provide some information about how SmarterMail appears in IIS: the Site Name, a Hostname, IP and Port (if these are needed — by default, SmarterMail binds to localhost on all IPs over port 9998). You can also change where SmarterMail installs by modifying the default File Path.
- Finally, you're given an overall summary of the installation. Clicking Install will install SmarterMail.
- On new systems, that haven't had SmarterMail installed, the installation process takes care of any additional set up and configuration that's necessary: setting up SmarterMail in IIS with an application pool and website, setting the proper permissions on both, etc.
- After the installation completes, you'll be presented with the Welcome to SmarterMail screen.
Welcome to SmarterMail
After SmarterMail is installed, a window opens in your default browser that takes you to the web interface for your installation. The URL used will match what was configured during the setup process, and if nothing was changed (e.g., no changes to the hostname or port), your browser will open localhost:9998/interface/setup#/.
The first thing you'll do is select which version of SmarterMail you want to install: Professional or Enterprise, or SmarterMail High Availability.
- SmarterMail Professional or Enterprise - This is the typical, single server installation of SmarterMail.
- SmarterMail High Availability - This is the installation process for installing a node (either the first node or subsequent nodes) that resides in a SmarterMail High Availability cluster. SmarterMail High Availability requires a partnership with SmarterTools. For more information, contact sales@smartertools.com.
After selecting your installation type, you'll set up a few pieces of information to get started using SmarterMail:
- You'll create the primary system administrator account
- You'll set the default base path for storing all SmarterMail data. This includes domain data, spool, log files, and POP and IMAP retrieval data, etc. By default, this path is C:\SmarterMail\
Once you have set up this information, you will be redirected to the webmail interface and automatically logged in to SmarterMail using the system administrator you created. From there, you can add in your first domain, then add users to that domain, you can modify your default domain template, adjust the security settings as needed, and more.
Upgrading SmarterMail
To upgrade SmarterMail, run the installer for the new Build on your server. The installer finds your existing installation (SmarterMail 16.x or later), stops the SmarterMail service, replaces the program files and starts the service again. If SmarterMail uses an existing IIS site, the installer also stops and restarts that site's Application Pool. Your domains, users, settings and data aren't touched, and you don't need to uninstall the current version first.
The installer won't install an older Build over a newer one. To roll back to an earlier Build, uninstall SmarterMail using Add or Remove Programs (this removes only the program files, not your data), then run the installer for the Build you want. See Things to Know for the earliest Build you can roll back to.
If you set the SmarterMail service to log on as a specific account, note that upgrading with the .EXE reinstalls the service under the Local System account. Set the account again after the upgrade, or upgrade using the command line installer, which lets you pass the service account each time.
Upgrade Process
To upgrade SmarterMail, do the following:
- Back up your SmarterMail data or take a snapshot of your VM. This gives you something to fall back on if something goes wrong during the upgrade.
- Download the latest version of SmarterMail from our website.
- Optionally, stop the SmarterMail website and its Application Pool in IIS. The installer stops the Application Pool on its own, but stopping the site first keeps users from reaching it partway through the upgrade.
- Run the installer.
- Walk through the installer as you did for the original installation. Most fields carry over from your existing installation, including the installation path and the SmarterMail site in IIS, so keep them as they are. If the .NET 10 Hosting Bundle isn't installed, the installer downloads and installs it for you.
- If you stopped the SmarterMail site in IIS, start it again and confirm everything loads correctly.
- After the upgrade finishes, you're taken to the SmarterMail login page, where you can log in with your existing system administrator account.





Things to Know
While the installation of SmarterMail is quick and easy, there are a few things to be aware of, especially if you're upgrading from a Legacy version of SmarterMail (SmarterMail 16.x or earlier) to a new Build:
- Due to significant back-end changes in recent versions of SmarterMail, it is not possible to roll back to a version earlier than Build 8495 (April 5, 2023). The installer also won't install an older Build over a newer one, so to roll back you'll need to uninstall the current version first.
- When performing an upgrade from a legacy version to the most recent current Build, all domains will go through a conversion process and all users will be re-indexed. The re-indexing of users is handled in batches, so it can take time to complete, especially if you have a lot of users on the server.
- This conversion process should go smoothly, and it can be tracked by going to https://your-smartermail-domain/interface/convert-status. You will need to log in with the system administrator account, but that page will list every domain on the server and its status as the conversion happens.
- If you run into errors at any point during the conversion process, please contact the SmarterTools Support Department. Be sure to provide a screenshot of the errors you're seeing in the SmarterMail interface as well as the conversion.log file from your SmarterMail Logs folder. (The default path is c:\SmarterMail\Logs.) Please send the full log file or copy and paste the snippet of text containing the domains showing an error.
- Legacy Versions of any product can be downloaded from your Account area. Simply log in to your account, and from the Account dropdown icon, select "Legacy Versions". Here you'll have access to any current Build plus the most recent release of any Legacy product.
- The Release Notes for all major and minor versions of SmarterMail, as well as Release Notes for all current Builds, are available on the SmarterMail Release Notes page of our website. It's a great idea to familiarize yourself with all the changes that have been made to SmarterMail between the version you're on and the version you'll BE on once you've upgraded.
- To ensure that the upgrade maintains the integrity of your data, settings, users, file structure, etc. it's important to keep any default settings "as is" during the installation of the upgrade. Only change default settings if they were changed for the version you're upgrading from. File paths, etc. should match exactly. For reference, the default installation path for new installations is C:\Program Files\SmarterTools\SmarterMail. Servers that were upgraded from older versions may still use C:\Program Files (x86)\SmarterTools\SmarterMail; keep whichever path your server already uses.
- If you are upgrading an installation that utilizes a license key, you WILL need to re-activate that key once the upgrade completes. Please be aware that license keys pertain to the version of SmarterMail you're running as well as the maximum version of SmarterMail you CAN run — you cannot activate a key on a more recent version of SmarterMail if your key does not support that version. However, all license keys are retroactive for previous versions.
- Choose to use the same IIS site that was used previously. If IIS was not previously configured, create a new
site.
Note: An IIS site is required in order to access the SmarterMail web interface. An IIS site can be configured after installation; however, you will not be able to access the setup wizard or web interface in the meantime. If you choose to configure the site later, you can access the IIS Configuration Tool in the IIS Tool folder of your SmarterMail installation (by default, C:\Program Files\SmarterTools\SmarterMail\IIS Tool).
Troubleshooting
- If the SmarterMail site fails to load, make sure that there is a site in IIS set up. You should be asked to create this during the installation, but if you pre-configured a site in IIS and had the installation use that site, make sure that site is pointed to SmarterMail's MRS folder. By default this is located at C:\Program Files\SmarterTools\SmarterMail\MRS. This folder contains the web.config file you will need, as well as a few error pages in case SmarterMail cannot be reached. (Make sure to choose site bindings that are appropriate for your environment.)
- Ensure both the Application Request Routing and URL Rewrite modules are installed.

- Ensure ARR and the URL Rewrite modules are configured correctly. See below.
Configure the Application Request Routing Module
Here is how the ARR module should be configured. Double click the module name then, on the right side of the IIS interface, click on Server Proxy Settings.
- Enable Proxy should be enabled. (I.e., be checked.)
- HTTP version: should be set to "Pass through".
- Keep alive should be enabled (checked).
- Time-out (seconds): should be set to 1200.
- Reverse rewrite host in response to headers should be disabled (unchecked).
- Under the Customer Headers area:
- Preserve client IP in the following header: X-Forwarded-For
- Include TCP port from client IP: ON
- Forwarding proxy header value: should be blank.
- Under the Cache Setting area:
- Memory cache duration (seconds): 0
- Enable disk cache: Unchecked
- Enable request consolidation: Unchecked
- Query string support: Ignore query string
- Under the Buffer Setting area:
- Response buffer (KB): 4096
- Response buffer threshold (KB): 0
- Under the Proxy Chain area:
- Proxy server: blank
- Under the Proxy Type area:
- User URL Rewrite to inspect incoming requests: Unchecked
- Enable SSL offloading: Checked (it should be by default)
Configure the URL Rewrite Module
Here is how the URL Rewrite Module should be configured. Double click the module name then, on the right side of the IIS interface, click on Server Variables.
- Click on Add. A modal window will open. Add the following variables (you will need to click
Add for each variable):
- HTTP_X_FORWARDED_FOR
- HTTP_X_FORWARDED_HOST
- HTTP_X_FORWARDED_PREFIX
- HTTP_X_FORWARDED_PROTO
All other configurations will be pulled from the web.config file that is installed as part of SmarterMail.
Upgrading Failover Servers
For organizations running SmarterMail Enterprise in a failover configuration (two SmarterMail servers that share domain, user and data files on a network share or NAS), each server is upgraded separately. The installer doesn't have access to the shared storage, so the SmarterMail service is stopped on both servers during the upgrade, and each server's service must log on with an account that can read and write to the share.
Upgrading the Primary Server
For the purposes of this upgrade process, the "Primary Server" acts as the default SmarterMail server and manages the licensing of the server cluster, whereas the "Secondary Server" remains connected to the cluster and is available as a hot standby.
- Stop the SmarterMail service on both the Primary and Secondary Servers. Perform the rest of these steps on the Primary Server.
- Run the installer for the new version of SmarterMail. You don't need to uninstall the old version first.
- The installer starts the SmarterMail service when it finishes. Stop the service again.
- In Services, right-click the SmarterMail service, select Properties and open the Log On tab. The upgrade resets the service to the Local System account, so set it back to the account that has permission to access the shared directory.
- Start the SmarterMail service. If you're upgrading from a version that still uses failoverConfig.xml on the shared drive, it's converted to failover.json and saved in the Service\Settings directory.
- Verify that the domains loaded properly.
Upgrading the Secondary Server
- Stop the SmarterMail service on the Primary Server. Perform the rest of these steps on the Secondary Server, where the service should still be stopped.
- Run the installer for the new version of SmarterMail.
- The installer starts the SmarterMail service when it finishes. Stop the service again.
- In Services, right-click the SmarterMail service, select Properties and open the Log On tab. Set it back to the account that has permission to access the shared directory.
- If this upgrade converted failoverConfig.xml to failover.json, edit the Secondary Server's failover.json so it matches the one on the Primary Server.
- Start the SmarterMail service on both the Primary and Secondary Servers.
- Verify that the domains loaded on the Secondary Server match the Primary Server.
After both servers have been upgraded, test that failover works as expected and that any backups you run are still working.
Steps for Upgrading Legacy Versions
When upgrading a legacy version of SmarterMail, such as SmarterMail 16.x or earlier, it's very important to understand the current version and how much different it will be than the version you're upgrading from. SmarterMail has not only improved greatly from legacy versions, but it's gone through a few interface changes along the way. This is especially noticeable if you're upgrading from particularly older versions of SmarterMail to a current Build.
In addition, we've previously recommended that customers upgrade in steps when coming from SmarterMail 14.x or earlier. However, this is no longer the case: the latest installers accommodate for all of the back end changes we've made since those versions, so it's no longer necessary to step up to SmarterMail 7.x, then SmarterMail 15.x, then on to the latest Build. In fact, it's NOT a good idea to upgrade in steps as you can carry forward any types of corruption or issues you may be having — even if you don't notice them. There can be back end file issues that you don't see, but that break an installation if you step through upgrades. Doing a standard upgrade to the latest Build should account for any of those issues and account for them in some way: either by fixing the issues or preventing those issues from corrupting any domains or users once the upgrade is complete.
That said, if you're at a point where you're upgrading from SmarterMail 15.x or earlier, we'd be happy to help you out: simply contact our Sales or Support Department and we can help test the upgrade for you, BEFORE you actually start through the process. Doing this will allow us to troubleshoot any issues you may encounter during the upgrade, and either fix them for you or help set your expectations of what you'll see once the upgrade completes.