Using Applescript in an Apple Mail rule

Just spent a few hours trying to figure out how to correctly fire a script from a Mail rule.

I was originally using this syntax from here as it seemed to be posted most places and used the handler construction that is similar to the one used by Hazel, but couldn't get the script to work.

on perform_mail_action(theData)
   tell application "Mail"
      set theSelectedMessages to |SelectedMessages| of theData
      set theRule to |Rule| of theData
      repeat with a from 1 to count theSelectedMessages
         — Process the current message
      end repeat
   end tell
end perform_mail_action

I eventually found this page with the following syntax that works perfectly - I should have known that Apple would provide an example script!

For reference "/Library/Scripts/Mail Scripts/Rule Actions/Sample Rule Action Script.scpt." is repeated here:

(*

Sample Rule Action Script

Copyright © 2003–2013 Apple Inc. All rights reserved.

You may incorporate this Apple sample code into your program(s) without

restriction.  This Apple sample code has been provided "AS IS" and the

responsibility for its operation is yours.  You are not permitted to

redistribute this Apple sample code as "Apple sample code" after having

made changes.  If you're going to redistribute the code, we require that

you make it clear that the code was descended from Apple sample code,

but that you've made changes.

*)

(*

This script is an example of how to write an AppleScript that can be

attached as a rule action. See Mail Help for details and Mail's 

AppleScript dictionary for the full terminology for the 'perform mail

action with messages' handler.

If you attach this script to a rule action, and the rule

matches an incoming message, a dialog box will display, showing

the name of the rule that matched and the subject of the message

that matched. One dialog per matched message will appear.

This is also an example of how you can write scripts that appear in the

Scripts menu and can pass in parameters for the selected messages and/or

mailboxes in Mail's main viewer window.

*)

using terms from application "Mail"

on perform mail action with messages theMessages for rule theRule

tell application "Mail"

set theText to "This AppleScript is intended to be used as an AppleScript rule action, but is also an example of how to write scripts that act on a selection of messages or mailboxes." & return & return & "To view this script, hold down the option key and select it again from the Scripts menu."

repeat with eachMessage in theMessages

set theSubject to subject of eachMessage

try

-- If this is not being executed as a rule action,

-- getting the name of theRule variable will fail.

set theRuleName to name of theRule

set theText to "The rule named '" & theRuleName & "' matched this message:"

set theText to theText & return & return & "Subject: " & theSubject

display dialog theText

set theText to ""

end try

end repeat

if theText is not equal to "" then

display dialog theText buttons {"OK"} default button 1

end if

end tell

end perform mail action with messages

end using terms from