This post will go over common troubleshooting steps to help you set up the correct email rules to get the behavior you want.
First off, this post only covers the PRO versions in depth. For the free version, refer to the free download page for instructions.
The assumption for the rest of this post is that you are using the global rules tab to setup the download.
So global filters are critical for the best use of the PRO Client and PRO Server versions. If you have not already setup global filters or rules, the recommendation is to do that as soon as possible.
Here are a few blog posts to help educate yourself about the PRO product and the use of global filters:
- IMPORTANT (READ THIS FIRST): Setup global filters for your email attachment processing. Learn about filters, extractions, save locations and actions inside a rule.
- If you work with multiple email accounts, learn how to set them up using global filters — multiple email accounts setup
- Configure the rules to save email bodies or attachments as PDF or other formats.
- Understand the intricacies of setting up rules to extract data from emails or attachments. Then use that extracted data in actions.
- If you work with databases, learn how to save or read data from a database and use them in your actions.
Bookmark the tips and tricks page for tips on how to use the program.
Why did my rule not work?
To answer this and/or other questions like why the rule did not download the attachment or email, enable Rule Tracing.
The best way to troubleshoot any rule is to enable this new feature we have introduced called Rule Tracing. So rule tracing helps you trace through what happened when a connect and download was initiated.
Rule tracing walks you through how the program decided to process the emails. It helps you understand which rules matched or did not match for every email or attachment that was processed!
Only the latest build (v 3.2.1015 or later) has this new Rule Tracing functionality. So make sure you upgrade to this latest build.
Upgrading is easy. All settings are always preserved while upgrading.
NOTE for PRO Server users: If you are running a service, uninstall the service from the Service tab first. Not doing this may interrupt the installation of the latest build.
- Free instructions — If you are using the free version, just go to our website to get and install the latest build.
- PRO instructions — If you are using the PRO versions, use the SAME link that you received in your license email to install the latest build. Your settings will be preserved with the upgrade.
How can you tell which build you are on?
To check the build you currently have, hover the mouse over the main title text (i.e. “Mail Attachment Downloader”) in the main program window.
You should see a popup with the version eg. 3.2 and the build 3.2.955.0 (955 is the build) as shown above.
How do you enable rule tracing?
It’s easy, just go to the Global filters tab and check the Rule Tracing checkbox (see the red text box highlight).
The search icon next to the Rule Tracing checkbox will not show anything until you run a Connect And Download session.
IMPORTANT: Before running a trace…
To make sure the program has a chance to process all email, do the following:
- Uncheck the Exclude inline attachments checkbox inside every Global Rule that has the control enabled
- Go to Global Filters tab -> Search in ->
- Select Messages Since Last Download radio button if you are SURE there is new email that meets the criteria
- Select All mail radio button to scan all email from the start of time. The program will then scan all email (this setting will apply for every account).
- Check the Inline content button
Running a trace…
Once you have enabled rule tracing, you will need to run a connect and download to test it out.
But before we proceed, a little advice for PRO Server service users follows…
- If you are running the PRO Server and a service, uninstall the service first so you can troubleshoot the issue using a normal connect and download.
- If you are having troubles with the service itself and the connect and download is working fine here’s what to do. The most likely cause for this is that you have not uninstalled and re-installed the service from within the program after changing some configuration. Config changes only take effect in the service after uninstalling and re-installing the service from within the program’s service tab.
Before running a connect and download, we recommend setting up the rules so you focus on the problematic email or attachment. To do so, you may need to disable certain rules (right click and disable them).
Or you may need to change the Search criteria (Search in… section) to All mail and alter the dates (Search between dates… section) when you want the program to process emails.
This way when you run the connect and download we won’t process all emails again but will just focus in on the specific email or attachment you want to troubleshoot.
Now click Connect and Download to initiate the trace and let it finish.
Analyzing the trace…
Once the connect and download has finished, switch back to the Global filters tab. Then click the Search button next to the Rule Tracing checkbox.
This should bring up a popup window something to the effect of the below.
Now lets look at how to analyze the information presented in this window.
Step-1: Select the download session based on time shown that you want to analyze.
Step-2: Select an email that should have downloaded emails or attachments or should have run rules or actions and you think there’s an issue with it.
Step-3: Look at every part or attachment of the email and drill down into which rules ran and which rules matched or did not match and why.
NOTE: Rules are run ordered from top to down (in the order they show up in the Global filters tab). So if a rule matched, no more rules under that rule will run. You can change the ordering in the Global filters tab by dragging and moving a rule around.
With this you should be able to find out why one or more rules did not download any attachments. And then you should be able to tune the rule configurations to ensure that it does what you want it to do.