Mail Attachment Downloader PRO Server - How To
Mail Attachment Downloader PRO Server can run as a Windows service, so downloads keep running on schedule in the background, even when nobody is signed in to Windows. This page shows how to get the service installed and running the first time.
New for the service in version 3.4 (builds 1036 to 1041) and the latest 3.3 builds (1030 to 1035)
- Install checks everything first: every account must sign in and every save folder must be writable by the service's own Windows account. If anything fails, the install is undone and each problem is listed with what to do. More.
- Only the accounts the service uses are copied to it, and uninstalling removes the service's accounts and passwords.
- See what the service is doing: its sign-in and download errors show in the program, the status strip shows its last and next run, and its Download History stays available when it's stopped or reinstalled. A service with no email account to download, for example after its Log On account was changed in Windows Services, now stops and says why in Event Viewer. More.
- "Reinstall to apply changes" appears on the Service tab when you change a setting while the service is installed. More.
- Connection Diagnostics can show the service's runs, and Submit a bug report can include the service's logs and data.
- Send email from Microsoft 365 app-only accounts (your own app registration with a client secret, for example for a shared mailbox) now works, and the copy is kept in that mailbox's Sent Items.
- Calmer license checks: when gearmage.com can't be reached, the service says why, gives up after 30 seconds instead of up to 100, and tries again up to once a minute instead of every second. It also shows its real name in Event Viewer.
- A banner instead of a popup: when the program isn't running as an administrator, a banner at the top offers Relaunch as admin or Always run as admin, instead of a popup at every start.
- Updating: the program offers updates, and its installer updates the service with it (uninstall, install, reinstall), so the program and the service stay on the same build. The service never updates itself.
- Security: the service's saved passwords and sign-in tokens are better protected. Existing installs are updated the next time the service starts.
All release notes, build by build.
Get the latest build
Before contacting support, or if anything doesn't work as expected, check for a newer build of the PRO version you bought (v2.x or v3.x). Download it from the link in the license email you received with your serial, and follow the steps in How to get the latest build. The version can stay the same (for example 3.3) while the build is newer. Build 1036 starts version 3.4; earlier builds are version 3.3. The release notes list what changed in each build.
To see which build you have, hover over the title "Mail Attachment Downloader" in the program's main window. It shows the version and build, for example version 3.4, build 1036.
Your settings are kept when you upgrade. We still recommend a backup first: use the Export/Import tab, or open the Logs tab and click Settings Folder under Client, which can save the settings as a zip file.
Upgrading? Uninstall the service from the Service tab first, install the new build, then install the service again. Its Download History is kept. If Sysinternals Process Explorer is running, close it: it can stop the service from being fully uninstalled. If the service still won't uninstall, see "The service won't stop or uninstall" in How to get the latest build.
Before you install the service
The service runs with a copy of your settings, under its own Windows account. Get everything working in the program first, then install:
- Each account works on its own. Set it up and click Test Connection in the mail server settings. See Set up your mail account and Check that your account is set up correctly.
- Save Password is ticked for every account that uses a password. Accounts that sign in with the browser (Gmail, Outlook.com, Microsoft 365) don't need one.
- A Connect and Download from the program works, with the rules you want the service to run.
- Save folders are reachable by the service. Network folders must be UNC paths such as
\\server\share\folder, not mapped drive letters: the service can't see mapped drives. - In the Options tab, the Schedule is None (no auto download) and After login run the program with this account is unticked. The service has its own schedule, and the install won't start while these are on.
- The program runs as administrator (right-click it and choose Run as administrator), so it can follow the service's status. The install asks for administrator permission either way.
Microsoft 365 and Google Workspace accounts take the sign-in you made in the program with them, and your organization's sign-in policies or a password reset can end it. You can sign in through your organization's own app registration instead. For Microsoft 365, app-only access (with a client secret) doesn't depend on anyone's sign-in, so the service keeps running. Setup guides: Microsoft 365 (Entra) and Google Workspace. See also Custom app registration.
Proton Mail users: the service downloads through Proton Mail Bridge, so Bridge must be running too, signed in as the same Windows user. Downloads fail until Bridge starts.
Install the service
- Choose the account (1) in the Account dropdown of the main window: the service downloads for this account only. For several accounts, pick <multiple@multiple>, click Choose Accounts, tick them and click Validate and use selected. Do this before installing.
- Leave Service Type on LocalSystem (2). See Service Type below if you need the service to run as a specific user.
- Set Duration (check every) in hours and minutes, more than 0, and tick Auto start on bootup (3). Leave Skip validation unticked, so the install checks your accounts.
- Click Install service (4) and allow the Windows prompt. The status lines show the install's progress, such as "Validating email settings for…". The button changes to Uninstall service when it's done.
- Check the status (5): Service Status says running, and the service downloads every time the Duration passes, even after you sign out of Windows.
What the install checks
The service only starts if everything it needs works. For each account it will use, including accounts that "Send mail" rule actions send from, the install:
- copies just that account's settings, and its password into the service's own encrypted store;
- signs in to the mail server, as the service;
- checks that the account's save folder, and the save and "Copy saved file" folders of its rules and of the global rules, can be written to by the service's Windows account. It does this by writing and deleting a small test file.
If anything fails, the install is undone and one message lists every account or folder with the reason (for example access denied, or a mapped drive the service can't reach) and what to do. Fix them, or deselect the account, and click Install service again.
Check that the service is working
- Status strip: the black strip at the bottom of the main window shows a green dot with the time of the service's last run, the files it saved and its next run. While the service downloads, it shows the same progress, spinner and counts as a download from the program.
- Errors: the service's sign-in and download errors show in the status list as "<ERROR from service> <account>" rows, with a notification, and say what to do. For example, when a Gmail or Microsoft sign-in has been revoked: sign in again in the program, then reinstall the service. For Microsoft 365, app-only access avoids this.
- Download History: choose Service History in the Download History tab to see every service run and file, also while the service is stopped or uninstalled. Use the Account, Session and Failures only filters to narrow it down.
- Sync status: the refresh button next to Service Status also copies each account's download state from the service, so a Connect and Download from the program doesn't download the same emails again. Click Sync status to see when each account was last synced.
Changing settings after the service is installed
The service uses the copy of your settings it got when it was installed. Changes you make in the program don't reach it until you reinstall it. When you change a setting while the service is installed, the Service tab shows Reinstall to apply changes.
- Click Uninstall service. This stops the service and removes its copy of your accounts and passwords.
- Make your changes, and test them with Connect and Download.
- Click Install service again. The service's Download History is kept.
Service Frequently Asked Questions
Changing configuration settings after service installation
Once you have successfully installed the Windows service, any changes you make to any configuration as a user will NOT take effect on the service. The service has a copy of the configuration from the time you installed it, and the Service tab shows Reinstall to apply changes when you change something.
To apply your changes, uninstall the service, make the changes, then install the service again. See Changing settings after the service is installed.
Service Type
By default the service is installed with the 'Local System' account. This is the recommended setting.
Alternatively, you can select 'User' from the Service Type dropdown to restrict access. Please note that when you select 'User', the account should have Local Administrative rights for it to work properly.
If you choose to install the service as a User or non-administrator, it will require more effort to ensure the service has all write permissions in all the right places in order to enable it to start up successfully. Support for this kind of non-administrative type of account is limited at this time.
Network folders are reached with the service account's network identity. For LocalSystem that's the computer's account (for example DOMAIN\PC$), so the share must allow that computer to write to it.
Read and Write access to all necessary folders
The account the service runs as (see Service Type) needs read AND write access to every save folder: each account's save location and the save and "Copy saved file" folders of its rules and the global rules.
Since build 1036 the install checks this as the service's own Windows account, by writing and deleting a small test file in each folder, and lists every folder it can't write to with the reason. Use \\server\share paths for network folders: the service can't see mapped drive letters. You can run the same check before installing with Validate and use selected in the Choose Accounts window.
Troubleshoot service install or startup
A failed install lists each account or folder that failed and what to do, and undoes itself, so you can fix the problem and click Install service again. See What the install checks.
For more detail, open the Logs tab and click Logs Folder under Service (StartServiceLog.txt covers the install and start), or open 🩺 Connection Diagnostics and switch to the background service view to see its sign-ins and runs.
Still stuck? Click 🐞 Submit a bug report... in the Logs tab and choose to include the service's data. We should be able to look into your issue within a day.
Viewing service running status
When the program runs as administrator, the status strip at the bottom of the main window shows a green dot with the service's last run, the files it saved and its next run, and the service's progress and errors show in the status list. Each run shows its start time, frequency and, for several accounts, which account it's on (for example "account 1 of 2").
If you start the program as a regular user, it can't follow the service's progress. To start it as an administrator, right-click the program's shortcut (or MailAttachmentDownloader.exe in its folder under C:\Program Files (x86)\GearMage) and choose Run as administrator.
If the service status doesn't say running, check ServiceLog.txt in the service logs folder (Logs tab, Logs Folder under Service).
You can also view the Download History (download history tab next to Current Status tab) and then select Service History from the dropdown on the far left. This will show you a file history of all files downloaded by the service. Also, the Download Chart will reflect the service download history. You can search through history through the Download History tab.
Email Account
When you install the Service, the service will only install and download attachments for the Email account you've selected from the dropdown with the same settings you have for that email account.
If you want the service to run for multiple accounts, pick <multiple@multiple> in the Account dropdown, click Choose Accounts and select the accounts, then install the service. Only these accounts, and any accounts that "Send mail" rule actions send from, are copied to the service. If one account fails during a run, the others still run.
Passwords for email accounts
You MUST have the Save Password checkbox checked for all accounts that sign in with a password and that you want the service to download attachments for. The install copies each password into the service's own encrypted store. Accounts that sign in with the browser (Gmail, Outlook.com, Microsoft 365) take their sign-in with them instead.
If you change a password, or a provider cancels an app password, update it in the program and reinstall the service.
Frequently Asked Questions
How do I run multiple accounts for every Connect And Download?
Pick <multiple@multiple> in the Account dropdown of the main window, click Choose Accounts, tick the accounts and click Validate and use selected. Then click Connect And Download. See Download from several accounts at once.
What are Global filters and why do I need them?
In the Free version, you had various tabs to specify how to filter the emails down. In the PRO version, we recommend you use the Global filters (tab) instead. We have this blog post explaining how to move from the Free configuration to the Global filters configuration. Please read it in its entirety before contacting support.
Global filters are what allows you to take various actions (like document conversion, copying or deleting emails after download).
How do I re-order Global filters?
Hold the Ctrl button and drag and drop the rule in the Global filters tab.
Why does it download all my mail the first time I run it?
The program identifies new mail based on when it last successfully downloaded attachments.
So when you run it for the first time, since no attachments have been downloaded yet, it will download all mail attachments in your email inbox after which it will only scan for mail attachments that arrive from thereon (including read and unread mail).
The default setting will only download messages since last download including unread mails that have not been downloaded by the program. IMPORTANT: If you switch this setting to All mail at any time, any state will be lost and the next time you select messages since last download it will download from the start again. To avoid this, select a date filter (see FAQ below titled "How do I download from a given date?").
Subsequent runs by clicking the 'Connect And Download' button will download remaining mail attachments that have not been downloaded yet until it has downloaded all attachments till the present day.
How do I download from a given date?
If you don't want to wait to download all email attachments the first time when messages since last download option is selected in the Search tab for the account, do the following.
If you are using Global filters tab:
If you look at the search tab, date filters should be disabled. This is because Global filters has rules defined within. To make an initial download from a date when using Global Filters, in the Global FIlters tab set the Start Date to the day you want to download from. This will ensure that the first download is always from that date. Subsequent Connect And Downloads would only check for new messages if you had selected "Messages since last download" option in the Search tab for that account. You can always select "All mail" to re-download the older mails from that date again.
If you are NOT using Global filters tab:
Set the 'start date' from which you want to download your attachments in the Search tab. Leave the 'end date' unchecked to indicate that there is no end date.
How do I re-download the same attachments?
If you you want to re-download the same attachments that the program had already downloaded in the past, choose Search -> Check In -> All mail. You may also want to check the Inline Content checkbox if you want to download attachments that are inlined. For certain types of mail servers this will be checked by default.
Google blocked the sign-in or sent me a security alert
Google doesn't accept passwords from other programs. Gmail and Google Workspace accounts sign in with Google in your web browser instead: make sure Gmail is selected in the mail server settings, click Test Connection, and sign in when your browser opens. See Signing in with your browser.
Google may send a "new sign-in" or "access granted" security alert the first time you allow the program. That's expected. More info about security
How do multiple rules work in Global filters tab?
Please read through the description here first for Global filters. Rules have the following components: Filters, Extractions, Save location/format and Actions. If the filters defined inside the rule matches an attachment or email body, then the file (which could be the body of the email) is saved in the specified save location and format inside the rule. Once the file is saved, the various actions are run. Rules are run from top/down order and ordering is important.
How do I test Global filters?
The best way to test Global filters (when you have many of them) is to create a new mailbox folder in your email account called something like "Test Mail Attachment Downloader". Then in the main program window, pick Selected folders and then check ONLY the "Test Mail Attachment Downloader" folder that you created. Then in the Search tab, pick "new messages since last download" and ensure Inline checkbox is checked.
Then move (do not forward) any emails you want to test into this folder using any email client of your choice (like Thunderbird, Outlook etc.). Then run Connect and Download to test whether the specific rule was applied. You can see which rule was applied in the "Download History" tab (next to "Current Status" tab towards the lower half of the main program window). If you see that the wrong rule was run for this test, make sure ordering of the rules is correct.
Make sure when you are done testing that you deselect the test folder that was selected for the test and then the folder you want to normally run on is selected.
Having trouble connecting?
Start with the message the program shows: sign-in problems now say what the provider needs. For Yahoo, AOL, iCloud and other providers under Other, click Set up <provider>… and follow the setup guide. Then open 🩺 Connection Diagnostics to see which stage fails.
You may be behind a corporate firewall or something may be blocking your connection. Check with your IT administrator to ensure that your host, port, TLS and IMAP/POP3 information is correctly entered and that you have a direct connection to the mail server. If the connection still fails, send us a bug report from the program.
I'm using gmail and some attachments aren't being downloaded.
Some attachments are inlined, check the 'Inline attachments' checkbox in the Search tab. If the attachment still doesn't download, contact issues@gearmage.com.
Why is Selected Folders grayed out?
Some mail servers only support the POP3 mail server protocol.
The POP3 protocol inherently does not support folders whereas the IMAP protocol does.
To overcome this, first, make sure that your mail server supports IMAP and then change the protocol via the Settings button to IMAP.
Setting the date doesn't seem to work
If you are using POP3 (in the mail server tab, see if POP3 is selected), the program will still need to scan/download (and throw away) attachments from the start of time even if the date is set.
File type limitations
A format of attached files that is sent by Outlook (TNEF) is not supported if your mail server does not convert them. These will be ignored by the program.
I see [THROTTLED] in the Status, what is that?
Some email providers like Gmail will end up throttling your connection if we end up processing too many requests for a given email account.
Where are the settings stored?
The program's settings are stored in the users %AppData%\MAD folder based on the logged on Windows user. The service keeps its own copy in C:\ProgramData\MADService. Open either from the Logs tab with Settings Folder under Client or Service, where you can also save them as a zip file.