Mail Attachment Downloader PRO- How To
Help for the PRO editions: setting up accounts, running several accounts at once, checking what was downloaded, and getting help fast when something doesn't work. Running the program as a Windows service? See the PRO Server how-to.
New for PRO in version 3.4 (builds 1036 to 1041) and the latest 3.3 builds (1030 to 1035)
- Setup guides for 23 mail providers (Yahoo, AOL, iCloud, Zoho, Proton Mail, GoDaddy, IONOS and more) under Other in the mail server settings. See how.
- Custom app registrations for IMAP: Microsoft 365 work or school accounts and Gmail / Google Workspace can now sign in through your organization's own app, not only Microsoft Graph. More.
- <multiple@multiple>: one failing account no longer stops the others, and Validate and use selected checks every account first. More.
- Connection Diagnostics and Submit a bug report for faster help. Exchange (EWS) accounts that sign in with Microsoft now connect to Exchange Online directly, without Autodiscover, which shows as its own stage when it runs. More.
- Rules: filter fields warn when they contain a
{VARIABLE}, and "Save to database" and "Lookup fields from DB" actions set up in older builds run again. - Open any rule from the rule window: the arrow at the end of the rule's name lists all your rules to search, sort and open, and Test this rule... stays open beside the rule window while you edit.
- Exclude inline attachments now works for IMAP (including Gmail) and POP3 accounts: logos and signature pictures are no longer saved, while attached files still are.
- Run webhook, Run AI prompt and Run Handlebars template: the email's fields such as
{SUBJECT}are filled in safely for a URL, JSON or XML, webhooks follow the Retries setting, and a failed call shows as failed. Document conversion can show the email's date in this computer's time zone. - New major versions and your license: a PRO subscription that is still active is offered a new major version, such as 4.0, as an update. A perpetual PRO license keeps getting updates of its own version, and is shown how to learn about and buy the new one.
- Security and privacy: passwords, sign-in tokens, API keys and other secrets are better protected.
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. The installer also shows the version on its Welcome page, and installing a new build upgrades the one you have.
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.
Using the background service? Uninstall the service in the Service tab before installing a new build, then install it again. See the PRO Server how-to.
Set up your mail accounts
The PRO editions use the same mail server settings as the free edition. Follow these sections of the main how-to:
- Add the account with Add account in the main window. The mail server settings open right away.
- Pick the right settings: usually filled in from your email address, including for your own domain.
- Sign in: with your browser for Gmail, Outlook.com and Microsoft 365, or with the setup guide for Yahoo, iCloud and other providers that need an app password.
- Check the account is set up correctly before you add rules or schedule downloads.
Custom app registration (your organization's own app)
If your organization doesn't allow our app to access mail, or the program runs unattended and you don't want sign-ins to expire and ask you to sign in again, register your own app and enter it in the Custom App Registration tab of the mail server settings:
- Microsoft 365 work or school accounts, with Microsoft Graph, Exchange or (since build 1030) IMAP. With a Client ID, Client Secret and Tenant ID, the program uses app-only access: it doesn't depend on a user's sign-in, so password resets and sign-in policies don't stop it. For IMAP you can also leave the Client Secret blank, so users sign in through your app. Sending mail over SMTP works with custom Microsoft 365 apps too. Set it up in Microsoft Entra.
- Gmail and Google Workspace with IMAP (since build 1030): the Client ID and Client Secret of your own Google Cloud OAuth client, of type "Desktop app". Users still sign in once, through your app. Set it up in Google Workspace.
It isn't available for POP3, Exchange on-premises or personal Microsoft accounts. Click Test Connection after entering the details and before saving: Connection Diagnostics shows which app registration was used and flags common mistakes. For the security side of app-only access, see Security.
Download from several accounts at once
- Set up and test each account on its own first.
- Pick <multiple@multiple> in the Account dropdown of the main window. The Settings button changes to Choose Accounts.
- Click Choose Accounts, tick the accounts to download from, and click Validate and use selected. Every selected account is checked, along with any account a "Send mail" rule action sends from, and every problem is listed at once.
- Click Connect and Download. The accounts run one after another. If one account fails, for example because its sign-in expired, the others still run, and the failure is recorded in the Download History.
Settings that belong to a single account can't be changed while <multiple@multiple> is picked. Hover over or click a disabled setting to see why.
See what was downloaded, and what failed
The Download History tab (next to Current Status) records every run, including sign-in, connection and folder errors, and which rule saved each file.
- Account and Session filters show one account, or a single run.
- Failures only shows only what went wrong. Search runs as you type.
- Each folder in the folder tree has a menu that opens its history.
- History is kept for 30 days by default. Change it next to Record download history, or click Clear history....
In the status list, rule actions (moving or deleting the email, scripts, webhooks, AI prompts and so on) get a tick when they worked and a cross when they failed. Failed actions and scripts that end with an error code are highlighted in yellow. See how webhooks are retried and report failures.
Get help fast
- Check the latest build (see above). Many problems are already fixed.
- Open š©ŗ Connection Diagnostics from the mail server settings or the Logs tab for sign-in and connection problems. It shows each stage of the latest connection with errors and timings. Passwords, tokens and secrets are never shown or included.
- Search our help: the knowledge base, the blog and the PRO info page.
- Send a bug report from the program. In the Logs tab, tick Verbose logging, make the problem happen again, then click š Submit a bug report.... Describe the problem, attach screenshots and choose how many days of logs to send (3 by default). Settings are included unless you untick them, and passwords never are. The report is emailed to support@gearmage.com with everything zipped.
To start over with clean logs, use Clear all logs... from the Logs Folder button.
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 settings are stored in the users %AppData%\MAD folder based on the logged on Windows user. To open it, go to the Logs tab and click Settings Folder under Client. From there you can also save the whole folder as a zip file. The background service keeps its own copy in C:\ProgramData\MADService.
Why is a filter field in my rule highlighted?
Filter fields match the text exactly as you type it, so a variable such as {DATE_LOCAL[yyyyMMdd]} in a filter never matches anything: variables only work in the saved filename format. The field is highlighted with a tip when this happens.
The saved filename format is highlighted when it combines {FILENAMEEXT} with {FILENAME} or {EXT}, which would repeat the name or extension.