Mail Attachment Downloader - How To

This guide takes you from installing Mail Attachment Downloader to your first download, and shows how to set up each kind of email account so it works the first time.

Get the latest build

Before contacting support, or if anything doesn't work as expected, check for a newer build on the download page, 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.

Quick start: your first download in five steps

1. Click Add account (1). The mail server settings open for the new account.
2. Type your email address in the Account box. The program picks your mail provider from the address and fills in the server for you. If the provider needs something first, such as an app password, an amber notice says so. Follow Set up your mail account below.
3. Click Test Connection, then Save. Gmail, Outlook.com and Microsoft 365 open your web browser so you can sign in with your provider (see Signing in with your browser).
4. Choose where to save the files (3). Click the folder button next to Save location to pick a folder, and the magnifying glass to open it in File Explorer while files download.
5. Click Connect and Download (4). By default the program downloads the attachments in your Inbox. Progress shows on the black status strip at the bottom: for example "76 of 180", the percentage, the time left and a Cancel link. Each file gets a tick when it's saved, or a cross if it failed.

To change an account later, choose it in the Account dropdown and click Settings (2).

To download from folders other than the Inbox, choose Selected Folders in the Folders and files tab and tick the folders you want. This needs IMAP, Exchange or Microsoft 365: POP3 has no folders, so the option is unavailable with POP3.

Choose exactly what to download

The tabs in the main window control what is downloaded and when:

• Folders and files: the mailbox folders to download from (the Inbox by default) and how the saved files are named.
• Search: new mail only or all mail, file types (documents, pictures, videos and so on), and a minimum email size such as 1 MB (the size of the whole email, attachments included).
• Filters: a date range, or only emails from certain senders or with certain words in the subject or body.
• Options: general program options, including a Schedule to check for new mail automatically.

Set up your mail account

The mail server settings open when you click Add account, or Settings next to the account. In most cases the program fills them in from your email address and you only need to sign in or enter a password. The numbers below match the picture.

1. 1Account: your email address. The box is also a dropdown of your saved accounts, so you can switch to another account's settings without closing the window. If you have unsaved changes, it asks whether to save or discard them first, and the main window switches to that account too.
2. 2Server type and mail server: pick Gmail, Outlook/Live, Yahoo Mail or AOL, or pick Other and choose your provider from the list. The list is in alphabetical order and ends with Custom host and port (IMAP or POP3) for any other mail server. The program usually picks the provider for you from your address.
3. 3Host, Port and TLS: filled in for the provider you picked. Leave them as they are unless your provider tells you otherwise. For Bluehost and IceWarp, the host starts as mail. followed by your domain: change it if your provider shows a different server.
4. 4Amber notice: appears when the provider needs something before it lets the program in, such as an app password or IMAP turned on. Click Set up <provider>… and follow the setup guide.
5. 5Test Connection, then Save: the program signs in and reports the result on the Status line. Keep Save Password ticked if you want scheduled downloads to run without asking.

Which settings should I pick?

Yahoo, iCloud and other providers: app passwords and setup guides

Many providers don't accept your regular password in other programs. Instead they need an app password (a separate password for one program), or they need access for other programs turned on first. The program knows what each provider needs and walks you through it:

1. Enter your email address in the mail server settings. Your provider is picked under Other (or Yahoo Mail / AOL). If it isn't, pick it from the list yourself.
2. Click Set up <provider>… in the amber notice. The setup guide opens.
3. Follow the guide's steps (pictured below), then click Save in the mail server settings.

1. AOpen the provider's page: the buttons take you straight to the right page, for example to create the app password. Name it "Mail Attachment Downloader" so you can recognize it later.
2. BPaste the password: the guide checks that it looks right. For example, Yahoo and AOL app passwords are 16 letters, and Apple's look like abcd-efgh-ijkl-mnop. If it says the password doesn't look right, you probably pasted your regular password.
3. CTest connection: signs in and opens your Inbox, and says what went wrong if it can't.
4. DUse this password: puts the password and server into the mail server settings. The status line then says "Connected to <provider>. Click Save to keep these settings."

What each provider needs

All of these connect with IMAP on port 993 with SSL unless noted. The setup guide in the program has the same steps, with buttons that open each page.

When the provider turns down the password

If a test or a download fails because the provider refused the password, for example a regular Yahoo password instead of an app password, the program explains what the provider needs. It works out the reason from what the server did, so this works even when the server answers in German, French or another language.

Gmail, Outlook.com and Microsoft 365: signing in with your browser

These accounts sign in with OAuth: you sign in on Google's or Microsoft's own page, and the program never sees your password. When you click Test Connection (or the first time you download):

1. The Authorization required window opens and shows the account being set up, then your web browser opens.
2. Choose the same account on the sign-in page, not another account your browser is signed in to.
3. Allow every permission. On Google, tick every checkbox before clicking Continue: unticked boxes aren't granted.
4. Go back to the program. It continues by itself once you've signed in.

If the program says "Some permissions weren't granted", follow this help article. For work or school accounts, the window's Copy for IT button copies the details your administrator needs. Read how we handle your data in our security and privacy policies.

PRO Organizations that don't allow our app, or that run the program unattended, can sign in through their own app registration instead, in the Custom App Registration tab of the mail server settings. It works for Microsoft 365 work or school accounts with Microsoft Graph, Exchange or (since build 1030) IMAP, where app-only access with a client secret doesn't depend on a user's sign-in, and for Gmail / Google Workspace with IMAP (since build 1030). Setup guides: Microsoft 365 (Entra) and Google Workspace. More in Security.

Microsoft 365 (Exchange Online) with Microsoft Graph

For Microsoft 365, Exchange Online and work or school Outlook accounts, choose Microsoft 365 (Microsoft Graph) as the Server type. You can also use it for personal Outlook.com accounts instead of IMAP.

Account: usually your email address (someone@contoso.onmicrosoft.com), or your username or domain\username. Tick Shared mailbox access if this is a shared mailbox.

If you type an address on your own domain and its mail is hosted by Microsoft 365, the program offers Use Microsoft 365 to fill this in for you.

Show the instructions for Exchange on your own server or legacy Exchange Web Services (EWS)

Check that your account is set up correctly

Before you rely on scheduled downloads, run through this list:

• Test Connection succeeded and the Status line says you're connected. Then click Save.
• Save Password is ticked, so scheduled downloads don't stop to ask for it.
• The Save location exists and you can write to it. For a network folder, type a \\server\share\folder path rather than a mapped drive letter.
• Your first Connect and Download finished with ticks next to the files. Files with a cross, or rows in yellow, failed: see why in the Download History tab.
• In the Download History tab, tick Failures only to see anything that went wrong, or filter by Account and Session to see a single run. Every run is recorded, including sign-in and connection errors.

Connection or sign-in problems?

1. Read the message. Sign-in problems now say what the provider needs and what to do. For app-password providers, click Open setup guide. For Gmail and Microsoft accounts, see Signing in with your browser.
2. Open Connection Diagnostics. Click 🩺 Connection Diagnostics in the mail server settings (or the Logs tab). It shows each stage of the latest connection and sign-in with timings, errors and TLS certificate details, and the error history. Passwords, tokens and secrets are never shown or included.
3. Check with your provider or IT. Make sure IMAP (or POP3 or Exchange) is turned on for your mailbox, and that a firewall or antivirus isn't blocking the connection.
4. Search the help desk for your error.
5. Send us a bug report. Turn on Verbose logging in the Logs tab, try again so the problem happens, then click 🐞 Submit a bug report.... Describe what happened and attach screenshots. The report includes the connection diagnostics and the logs, zipped, and emails them to support@gearmage.com.

Tip: if you changed several settings after a failed test and it still doesn't connect, delete the account with the trash button next to the Account in the main window and add it again with Add account. This clears any cached settings.

Frequently Asked Questions