Community Knowledge Base

Installation and Upgrade

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 -- both the .EXE and an .MSI -- are available on the SmarterMail Downloads page of our website.

Jump to:

Important IIS Information

Beginning with Build 8745, SmarterMail uses internal IIS features instead of the traditional “MRS” web application used in the past. As a result, the installer establishes some settings in IIS that system administrators will need to be aware of when installing for the first time or when upgrading. These settings are listed below and are here mostly for reference in case they conflict with other websites on the server. In some rare cases, sites with incompatible setups may need to be moved to separate servers.

Application Request Routing

Application Request Routing is configured at the server level in IIS. As such, settings configured therein may affect other sites on the server. The core settings that SmarterMail relies upon are listed below. These can be found in IIS by clicking on your server name on the left tree, then choosing “Application Request Routing” on the icon list, then choosing “Server Proxy Settings” from the right menu.

Enable Proxy

  • Required Value: ON

For SmarterMail to function properly, this setting must be enabled so that IIS can proxy to the web interface that the SmarterMail Service hosts on the backend.

Time-out (seconds)

  • Required Value: 1200 (or greater)

In order for long-polling protocols to function properly, this value needs to be set to 1200 seconds or greater. If this is too short, devices connected to SmarterMail will use more battery than necessary as they repeatedly reconnect.

Preserve client IP in the following header

  • Required Value: X-Forwarded-For

SmarterMail requires that this is set to “X-Forwarded-For” or else Denial of Service and Brute Force detection will not function properly.

Memory cache duration (seconds)

  • Required Value: 0

Memory caching seeks to reduce the load on your web servers by caching common outputs of requests. SmarterMail does its own caching, so adding additional caching to ARR only complicates the issue and may result in some API calls being out of date.

Enable disk cache

  • Required Value: OFF

Disk caching should be disabled for the same reason as Memory caching.

Response buffer threshold

  • Required Value: 0

In order for streaming protocols to work, including EWS, EAS, MAPI, and some parts of the web interface, data must be sent out as soon as it is available. The response buffer setting in ARR will delay the messages for a significant amount of time and will cause issues with some client devices.

Proxy Server

  • Required Value: None (leave empty)

Proxy server should be left blank, as it is configured with the URL Rewrite Module.

URL Rewrite Module 2

The URL Rewrite Module is the website-level filter that sends requests to the SmarterMail service from IIS. There are a few settings that are configured directly in IIS, but most of the properties for it are configured in the web.config file that resides in the MRS folder. (By default, that is C:\Program Files (x86)\SmarterTools\SmarterMail\MRS.)

To ensure all the appropriate headers get sent along, they must be added to the list of allowed headers. To verify these, go do your website in IIS, then choose URL Rewrite from the icons. From there, choose “View Server Variables” on the right side, and ensure that the following 4 items appear in the list. If they are not, they should be added:


Installing SmarterMail for the First Time


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:

  1. On the first page, you select the path for the installation and accept the license terms.
  2. 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.
  3. Once the activation information is provided, you'll see an overview of the SmarterMail version and mailbox allocation.
  4. 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. (NOTE: IF installing SmarterMail on new hardware with the intention of migrating domains and users from another SmarterMail server, it's best to ensure you're installing using the same File Path as your previous server to ensure migrated data and settings are preserved.)
  5. Finally, you're given an overall summary of the installation. Clicking Install will install SmarterMail.
  6. 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.
  7. 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#/.

On this Welcome page, 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.

MSI Installation for Legacy Versions

NOTE: As of SmarterMail Build 8747 (December 13, 2023), the MSI installation of SmarterMail is no longer available. This is due to improvements in SmarterMail. The .EXE available for installing SmarterMail can be used for manual installations, silent installs, etc. that were previously performed by the manual installer.

Some SmarterMail administrators, specifically those who work for web hosting companies or ISPs, prefer to manually install SmarterMail. This is especially true for those administrators who have automated the installation process using SmarterMail's APIs and their own internal systems. Regardless of how you do it, SmarterTools offers a .MSI for those customers who want to manually install SmarterMail. NOTE: When using the MSI to install current Builds of SmarterMail, you will want to use the latest ASP.NET Windows Hosting Bundle from Microsoft (recommended) in order to install the ASP.NET Core Runtime. It can be found on the Download .NET page of Microsoft's website.

  1. Identify the server(s) on which you want to manually install SmarterMail.
  2. Download the .MSI from the SmarterMail Downloads page of our website. This .MSI should be downloaded or moved to the server where SmarterMail will be installed.
  3. Run the MSI. This will ONLY install the SmarterMail program files on the server, which includes installation and start up of the SmarterMail service. It does nothing more.
  4. Next, create an App Pool for SmarterMail. Name it whatever you like, but when using the full installation application, it's named SmarterMail. Use the default settings for ".NET CLR version" and "Managed pipeline mode". (.NET CLR Version v4.0.30319 and Integrated, respectively.)
  5. Once your App Pool is created, create a site for SmarterMail. You can name it whatever you like, but if you name it "SmarterMail", IIS should assign it to the SmarterMail App Pool you created.
  6. When setting the "Physical path" for your new site, find the SmarterMail MRS folder. By default, this is C:\Program Files (x86)\SmarterTools\SmarterMail\MRS. If you've relocated the SmarterMail installation, you will want to find the path to the MRS folder.
  7. As for the port, you can use whichever port you like. We initially recommend using an alternate port for your initial installation -- like port 9998. Then, you can change the port to 80, 443, or whatever you like once you're ready for production.
  8. Once all this is completed, you should be able to navigate to the SmarterMail URL using either the Browse function within IIS, or manually typing the path in a browser. (E.g., http://localhost:9998, or whatever URL you're using for your SmarterMail installation.)
  9. The final steps are actually setting up SmarterMail. You can use the information in Installing SmarterMail for the First Time to complete the SmarterMail set up process.

Upgrading SmarterMail

Upgrading SmarterMail is a very simple process: you simply uninstall SmarterMail using Add Remove Programs, then run the installer you download from the SmarterTools website. Yep, it's really that simple. For those worried about uninstalling first, when you use Add Remove Programs, only SmarterMail's program files are removed: NONE of the data files are touched. So all of your users, domains, settings -- all of it -- is perfectly preserved and ready to use after you install the new version you want to run.

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).
  • 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 file path for SmarterMail is C:\Program Files (x86)\SmarterTools\SmarterMail.
  • 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 by navigating to its default location at C:\Program Files (x86)\SmarterTools\SmarterMail\IIS Tool.)
  • If you are running SmarterMail as an IIS site, IF NEEDED, change the .NET version of the Application Pool to .NET 4.0 and restart IIS.

Steps for Upgrading Legacy Versions

When upgrading a legacy version of SmarterMail, such as SmarterMail 15.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.

Upgrade Process

To upgrade SmarterMail, do the following:

  1. First, back up your current SmarterMail installation or take a snapshot of your VM. This will give you something to fall back on should something happen during the upgrade.
  2. Stop the SmarterMail website and associated Application Pool in IIS.
  3. Next, download the latest version of SmarterMail from our website.
  4. Uninstall the current version using Add or Remove Programs. This will only remove the SmarterMail program files -- no data or system files are touched. This is an important step and should not be skipped, especially if you're upgrading from an older version. Newer versions may not require this step, but it doesn't hurt.
  5. Run the installer.
  6. Upgrading is essentially like installing for the first time. The difference is that most fields will simply carry over based on your existing installation. So you'll walk through the installation just as you did when first installing the product but things like your paths, etc. will already be filled in. The upgrade process even finds the existing SmarterMail site in IIS!
  7. After the upgrade finishes, you're taken right to the SmarterMail login page where you can log in with your existing system administrator account.

Upgrading Failover Servers

For organizations running SmarterMail Enterprise in a failover configuration -- that is, 2 SmarterMail front ends that share the domain, user and data via a network share or NAS -- the upgrade process is a bit more complex. This is because the SmarterMail installer itself generally doesn't have access to the shared drive or NAS device. Therefore, it's not possible to make any modifications to the folders and/or data that is shared on those types of storage solutions. While an upgrade may not need to change any of those pieces, SmarterMail's upgrade process does still need access to them. Therefore, each server needs to be upgraded separately, with some files and folders moved temporarily during the upgrade.

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 other is considered the "Secondary Server" that remains connected to the cluster and is available as a "hot standby".

  1. Stop the SmarterMail Service on both the Primary and Secondary servers. The rest of these actions should be performed on the Primary Server.
  2. Uninstall the old version of SmarterMail via Add/Remove Programs.
  3. Install the new version of SmarterMail.
  4. Stop the SmarterMail Service again. (It will restart after the installation).
  5. Right-click on the SmarterMail Service and go to the Log On tab. Make sure the account being used has the proper permissions/credentials for accessing the shared directory.
  6. Start the SmarterMail Service. The old "failoverConfig.xml" on the shared drive should be converted to failover.json, which is saved in the Service\Settings directory.
  7. Verify that the domains loaded properly.

Upgrading the Secondary Server

Upgrading the Secondary Servers is a bit easier as you don't need to move files between the two servers.

  1. Stop the SmarterMail Service on both the Primary and Secondary servers. The rest of these actions should be performed on the Secondary Server.
  2. Uninstall the old version of SmarterMail via Add/Remove Programs.
  3. Install the new version of SmarterMail.
  4. Stop the SmarterMail Service again. (It will restart after the installation).
  5. Right-click on the SmarterMail Service and go to the Log On tab. Make sure the account being used has the proper permissions/credentials for accessing the shared directory.
  6. Start the SmarterMail Service. The old "failoverConfig.xml" on the shared drive should be converted to failover.json, which is saved in the Service\Settings directory.
  7. Stop the SmarterMail Service one more time.
  8. Edit the failover.json file to match the failover.json on the Primary Mail Server.
  9. Start the mailservice on BOTH the Primary and Secondary Servers.
  10. Verify that the domains loaded on the Secondary Server match the Primary Server.

After both servers have been upgraded, it's best to perform some tests to ensure that the failover acts as expected and that any backups being performed are working.