Creating a Rule in the Mail app to add messages to your OmniFocus 2 Inbox

OmniFocus 2 for Mac no longer includes preferences for configuring a mail rule, but this document can help you replicate the functionality of the rule that was included in OmniFocus 1. These instructions assume that you’re using OS X Mavericks or later (required by OmniFocus 2), and are using the OmniFocus 2 Pro feature set (since AppleScript support is a Pro-only feature).

Having looked into problems with Mail Rules extensively in the past, we’ve found that Mail.app simply fails to apply rules sometimes. We provide these instructions as a convenience for customers who prefer to use the Mail Rule, we but are no longer able to provide technical support for problems involving Mail Rules in Apple’s Mail.app. For most customers, using Mail Drop with Omni Sync Server will be a better experience.

Download and copy the script

Right-click and download this linked AppleScript file. In order for Mail to use it in a rule, it needs to be in a specific folder, so open the Finder and choose Go to Folder from the Go menu. Paste in the following line (including the ~) and press return.

~/Library/Application Scripts/com.apple.mail

A window will open showing Mail’s scripts folder; copy your downloaded MailAction.applescript file into the folder and close the window.

Configure a rule

Open Mail’s Rules Preferences pane and click “Add Rule”. Then, edit your new rule as pictured. If MailAction.applescript is in the correct folder, it will automatically be available from the pop-up.

The rule in the screenshot is configured to grab emails sent to yourname+omnifocus@example.com, but you could use other criteria if your email provider doesn’t support plus addressing.

Optionally, you can add extra actions to the rule to mark the incoming message as read, archive it, or delete it.

Test your rule

Send an email to yourname+omnifocus@example.com. When it arrives, Mail should run your new rule and a new item should be created. If nothing is happening, make sure that the script is being run by checking your console log for a line containing:

OmniFocus calling process_message in MailAction script

Advanced syntax

The way that messages are processed by the script is pretty detailed, and you have a lot of power in how you can format your items:

• The subject and body of the message are joined into a single block of text.
• The first line and any other lines starting with -- (double-hyphens) become new actions. Other lines become notes for the preceding action.
• To specify a project, use > (greater-than sign) or :: (double-colons), followed by a project name or abbreviation. The colons are nicer for the iPhone because they are on the first shifted keyboard rather than the less-accessible math keyboard. The project string is matched exactly as if it was entered in a project cell in OmniFocus.
• To specify a context, use @ (at sign), followed by a context name or abbreviation. Like project names, the context name is matched exactly as it would be in OmniFocus.
• To enter start or due dates, use # (number sign), followed by some date expression (like 9-30-2014). If there is only one date, it becomes the due date. If there are two (each with its own number sign), the first becomes the start date and the second becomes the due date.
• To enter a time estimate, use $ (dollar sign—time is money) followed by some duration expression (like 5m, 1h, and so on); you can use the same duration expressions that you use in OmniFocus.
• To flag the action, use ! (exclamation point) at the end of the action title.
• You can also add a note on the same line as an action title by separating them with // (double-slashes). Anything after the double-slashes becomes a note, but double-slashes in a URL like omnigroup.com don’t count.
• This AppleScript supports attachments as well, so this Mail Rule can bring along files that you attach to your email.