TweetFollow Us on Twitter

Introduction to Scripting Mail

Volume Number: 21 (2005)
Issue Number: 9
Column Tag: Programming

AppleScript Essentials

Introduction to Scripting Mail

by Benjamin S. Waldie

Email automation is usually popular among AppleScript developers using Mac OS X. By writing scripts to perform email-related processes, developers can automate processes such as sending batches of recipient-customized messages, archiving emails in text format or in a database, emailing status reports to administrators, and much more.

In this month's article, we will discuss using AppleScript to automate aspects of the Mail application, which comes pre-installed with OS X. If you don't use the Mail application, then you may want to explore some of the many other scriptable email clients and tools that are available for the Mac. Some of these will be mentioned later in this article.

Working with Accounts

In Mail, as with most email applications, users may have multiple email accounts, all with specific settings and configurations. AppleScript can actually be used to interact with these accounts, allowing you to automate the process of configuring accounts, retrieving account settings, and more.

Accessing Accounts

Let's get started by writing some code that will retrieve the name of every account in Mail, regardless of its type.

tell application "Mail"
   name of every account
end tell
—> {"AppleScriptGuru"}

For users that have multiple types of email accounts, the following example code will allow you to determine the exact class of a given account. Possible classes include imap, pop, smtp, and Mac.

tell application "Mail"
   account type of account "AppleScriptGuru"
end tell
—> Mac

The account class, along with a listing of its properties, can be found in the Message suite in Mail's AppleScript dictionary. Additional account properties are type specific, and are listed under the following separate classes, which inherit most of their properties from the main account class - Mac account, imap account, and pop account. See figure 1.


Figure 1. Account Classes in Mail

The following code will retrieve a listing of all .Mac accounts.

tell application "Mail"
   name of every Mac account
end tell
—> {"AppleScriptGuru"}

Accounts possess a number of other properties, which are accessible through scripting. While some properties of an account are read only, such as account type and password, others may be retrieved and adjusted by way of scripting. The following example code will retrieve all of the properties of a specified account.

tell application "Mail"
   properties of account "AppleScriptGuru"
end tell
—> {account type:Mac, compact mailboxes when closing:true, 
           empty trash on quit:false, move deleted messages to trash:true, 
           account directory:"/Users/bwaldie/Library/Mail/Mac-applescriptguru"...

Disabling Accounts

In some cases, you may have the need to disable an account entirely. In order to do this manually in Mail, you must do so by opening the Preferences window, navigating to the proper account, and deselecting a checkbox in a specific location. To disable multiple accounts, you would need to repeat this process for each account. However, this task can easily be automated with AppleScript.

The following example code demonstrates how to disable an account in Mail. To re-enable the account, simply change the false value to true.

tell application "Mail"
   set enabled of account "AppleScriptGuru" to false
end tell

It is important to note that, when disabling account with AppleScript, the account will automatically become re-enabled the next time Mail is launched.

Setting Account Passwords

As previously mentioned, most properties of an account can be modified via scripting, including the password for the account. The following code demonstrates how to change the password for an account.

tell application "Mail"
   set password of account "AppleScriptGuru" to "myPass"
end tell

For obvious reasons, AppleScript cannot be used to retrieve the password for an account.

tell application "Mail"
   password of account "AppleScriptGuru"
end tell
—> "Account passwords can only be set, not read."

Accessing SMTP Servers

When configuring an account, you may also need to configure its SMTP server. The following code shows how to retrieve a reference to the SMTP server of an account.

tell application "Mail"
   smtp server of account "AppleScriptGuru"
end tell
—> smtp server "smtp.mac.com:applescriptguru" of 
application "Mail"

Like an account, an smtp server is actually a class in Mail, and therefore, it possesses properties, many of which are modifiable.

tell application "Mail"
	set theSMTPServer to smtp server of account "AppleScriptGuru"
	properties of theSMTPServer
end tell
—> {account type:smtp, authentication:none, server name:"smtp.mac.com", ...

The following example code demonstrates how to retrieve a list of all SMTP servers in Mail.

tell application "Mail"
   every smtp server
end tell
—> {smtp server "smtp.mac.com:applescriptguru" of 
application "Mail"...

Working with Messages

While interacting with accounts may be beneficial for some, interacting with messages directly via AppleScript is probably a much more applicable topic to most. In Mail, AppleScripts may be written to generate and send new messages, retrieve information about messages, and more. First, we will discuss outgoing messages.

Generating an Outgoing Message

The following code demonstrates how to generate a new outgoing message. You will see that, during the creation of the outgoing message, I have chosen to assign values to certain properties of the message, including the message's subject and body.

tell application "Mail"
   make new outgoing message with properties {visible:true, subject:"My Subject", content:"My Body"}
end tell
—> outgoing message id 137230944of application "Mail"

In the code above, I also specified a value for the visible property of the outgoing message. The reason for this is that, by default, Mail will create new outgoing messages without displaying them. This makes it possible for you to write scripts that generate a new email message, without displaying the message to the user.

Adding an Attachment to an Outgoing Message

You may have noticed in the previous examples that, when creating a new message, a reference to the new message is returned as the result of the make command. Like any result, this reference can be placed into a variable, allowing you to continue referring to the new message.

One example of when this may be beneficial is when you want to insert an attachment into an outgoing message. In Mail, an attachment is not actually considered an element of a message. Rather, it is considered an element of the content of a message. Therefore, to insert an attachment into a message, you must tell the message to make an attachment within its content. The following example code demonstrates this process.

set theAttachment to choose file
tell application "Mail"
   set theMessage to make new outgoing message with properties {visible:true, 
   subject:"My Subject", content:"My Body"}
   tell content of theMessage
      make new attachment with properties {file name:theAttachment} at after last paragraph
   end tell
end tell

Adding Recipients to an Outgoing Message

So far, we have discussed creating a new message with a subject and body, and adding attachments. However, in order to send an outgoing message, you will also need to insert recipients. In Mail, outgoing messages may contain the following recipient classes as elements - bcc recipient, cc recipient, and to recipient.

The following example code demonstrates how to add a new to recipient to an outgoing message. A similar process may be used to add a new cc or bcc recipient.

tell application "Mail"
   set theMessage to make new outgoing message with properties 
      {visible:true, subject:"My Subject", content:"My Body"}
   tell theMessage
      make new to recipient at end of to recipients with properties 
         {name:"Ben Waldie", address:"applescriptguru@mac.com"}
   end tell
end tell

To add multiple recipients, you would use a repeat loop to continue creating new recipients at the end of the existing recipients.

Sending an Outgoing Message

Sending an outgoing message in Mail is very straightforward, and is done by using the send command.

send theMessage

Accessing Messages

In addition to generating and sending messages, you may want to write scripts that interact with messages that you have received. These messages may be located within your inbox, or within another mailbox. The following code may be used to retrieve the selected messages in Mail.

tell application "Mail"
   selection
end tell
—> {message 15 of mailbox "INBOX" of account "AppleScriptGuru" of application "Mail"}

You may notice, in the example above, that the result is an AppleScript list. This is because you may have multiple messages selected in Mail. Therefore, when retrieving the selection, you will most likely want to loop through the returned list of messages, processing each message appropriately.

Optionally, you may refer to a message by its index in a specific mailbox. For example, the following code refers to the first message of a given account in my inbox.

set theMessage to message 1 of mailbox "INBOX" of account "AppleScriptGuru"

Likewise, the following code refers to the first message in a locally created mailbox.

set theMessage to message 1 of mailbox "Filed" 

Reading Messages

Once you have generated a reference to a message in Mail, you can retrieve any of its properties. The following example code demonstrates how to retrieve the subject of the first selected message.

tell application "Mail"
   set theSelection to selection
   set theMessage to item 1 of theSelection
   subject of theMessage
end tell
—> "My Message Subject"

The following example code demonstrates how to retrieve the body of the first selected message.

tell application "Mail"
   set theSelection to selection
   set theMessage to item 1 of theSelection
   content of theMessage
end tell
—> "My Message Body"

Messages have numerous other properties that can be retrieved, if desired, including date sent, source (useful for HTML-based messages), and sender. Some properties of messages can also be changed with AppleScript, including the message's flagged status, junk status, and read status.

In addition to properties, messages may also contain recipients as elements, which can also be retrieved. The following example code demonstrates how to retrieve a list of the to recipients of a message.

tell application "Mail"
   set theSelection to selection
   set theMessage to item 1 of theSelection
   set theRecipients to to recipients of theMessage
end tell
—> {to recipient 1 of message 15 of mailbox "INBOX" of account 
   "AppleScriptGuru" of application "Mail"}

Once retrieved, you can loop through the recipients, retrieving any desired properties of those recipients.

properties of item 1 of theRecipients
—> {name:"Ben Waldie", address:"applescriptguru@mac.com", class:recipient}

Retrieving Message Attachments (Tiger Only!)

In Mail, retrieving attachments has always been a difficult task, and until the release of Mac OS X Tiger, it was all but impossible without some roundabout, complex scripting. In Tiger, there is finally a way to do it.

The following example code demonstrates how to save the attachments of a message into a specified folder.

set theOutputFolder to (choose folder) as string
tell application "Mail"
   set theMessages to selection
   set theMessage to item 1 of theMessages
   set theAttachments to every attachment of content of theMessage
   repeat with a from 1 to length of theAttachments
      set theAttachment to item a of theAttachments
      try
         set theAttachmentName to name of theAttachment
         set theSavePath to theOutputFolder & theAttachmentName
         save theAttachment in theSavePath
      end try
   end repeat
end tell

Filing a Message

Filing a message in a mailbox is not done by using the move command, as one might expect. Rather, to file a message, you must change the mailbox property of the message to a specified mailbox.

The following example code would file the specified message into a local mailbox named Filed.

tell application "Mail"
   set theSelection to selection
   set theMessage to item 1 of theSelection
   set mailbox of theMessage to mailbox "Filed"
end tell

Triggering Scripts from a Rule

One very useful feature in Mail is the ability to trigger an AppleScript from a rule. This can enable you to create a fully automated workflow to process incoming email messages. For example, you could write a script that will automatically send a customized thank you email to anyone who subscribes to your mailing list.

Writing a Mail Rule Script

A script that will be triggered as a Mail rule may be saved in a variety of ways, including as a compiled script, as text, or as an application. The main requirement is that the script must contain a perform mail action handler, which will be triggered by Mail when the rule processes on messages. This handler may be written in one of two manners.

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

In the example above, the handler's positional parameter, in this case theData (the parameter name may be set to any variable name desired), contains a record. This record contains 2 properties, |SelectedMessages| and |Rule|, which will be automatically populated by Mail with a list of messages on which the rule is triggered, as well as a reference to the rule itself. Using this information, you can write custom code to perform the desired tasks on the passed list of messages, or to retrieve information about the rule that was triggered.

The following is a second example of how the perform mail action handler may be written.

using terms from application "Mail"
   on perform mail action with messages theSelectedMessages for rule theRule
      repeat with a from 1 to count theSelectedMessages
         — Process the current message
      end repeat
   end perform mail action with messages
end using terms from

In the handler example above, you will notice that the parameters are specified individually as labeled parameters, rather than in a single positional parameter containing a record.

Again, either of the above handlers may serve as a Mail rule script. You may choose to use whichever you feel the most comfortable using.

Configuring a Mail Rule Script

Once you have written your Mail rule script, you will need to configure Mail to trigger it on incoming messages. To do so, open Mail's Preferences window, and click on Rules in the window's toolbar.

Next, click the Add Rule button, and configure the new rule to trigger according to the desired criteria. Finally, configure the rule to perform the Run AppleScript action, and specify the path to your saved Mail rule script. Figure 2 shows an example of a configured Mail rule script.


Figure 2. A Configured Mail Rule Script

Now, you are ready to begin using the rule to process messages with your script. The rule will be automatically triggered when incoming messages matching the specified criteria are detected. You may also trigger the rule manually on selected messages by selecting Apply Rules from the Message menu.

Other Options

As mentioned at the beginning of this article, there are a number of other Macintosh-based email applications and tools, which are also AppleScriptable. If you prefer not to use Mail, you are encouraged to explore these other options. The following are a handful of scriptable email clients and tools.

Microsoft's Entourage is a very scriptable commercial email client, which, in addition to offering email capabilities, also offers an integrated calendar, task list, address book, and more. Information about Entourage, along with other Macintosh-compatible Microsoft applications, can be found on Microsoft's website at http://www.microsoft.com/mac/.

Eudora, by QUALCOMM Incorporated, is another popular email client, which has great support for AppleScript. Eudora is available for free in Light mode, and is also available with additional features in Sponsored or Paid mode. General information about Eudora can be found on the main Eudora website at http://www.eudora.com. Information about Eudora's AppleScript support may be found at http://www.eudora.com/developers/scripting. html.

Xmail.osax is a Mac OS X scripting addition, written by Jean-Baptiste LE STANG. This scripting addition offers AppleScript developers a quick and easy way to send (not receive) email messages, without the need for an email client. This scripting addition can be great for scripts that need to send regular progress reports through email. Information about Xmail.osax, along with a download link, can be found on Jean-Baptiste LE STANG's website at http://lestang.org.

In Closing

Now that you have some idea of the types of tasks you can automate with Mail, you are encouraged to begin exploring Mail's AppleScript dictionary further. There are many other tasks that can be automated with Mail, which were not covered in this article. Basic information about Mail scripting, including an overview of sample Mail scripts that are included with OS X, can be found on Apple's website at http://www.apple.com/applescript/mail/. If you are looking for pre-existing scripts for Mail, or for other email clients, be sure to check out MacScripter.net's ScriptBuilders section at http://scriptbuilders.net/.

Until next time, keep scripting!


Ben Waldie is author of the best selling books "AppleScripting the Finder" and the "Mac OS X Technology Guide to Automator", available from http://www.spiderworks.com. Ben is also president of Automated Workflows, LLC, a firm specializing in AppleScript and workflow automation consulting. For years, Ben has developed professional AppleScript-based solutions for businesses including Adobe, Apple, NASA, PC World, and TV Guide. For more information about Ben, please visit http://www.automatedworkflows.com, or email Ben at applescriptguru@mac.com.

 
AAPL
$97.67
Apple Inc.
+0.64
MSFT
$44.50
Microsoft Corpora
+0.10
GOOG
$589.02
Google Inc.
-4.33

MacTech Search:
Community Search:

Software Updates via MacUpdate

TinkerTool 5.3 - Expanded preference set...
TinkerTool is an application that gives you access to additional preference settings Apple has built into Mac OS X. This allows to activate hidden features in the operating system and in some of the... Read more
Audio Hijack Pro 2.11.0 - Record and enh...
Audio Hijack Pro drastically changes the way you use audio on your computer, giving you the freedom to listen to audio when you want and how you want. Record and enhance any audio with Audio Hijack... Read more
Intermission 1.1.1 - Pause and rewind li...
Intermission allows you to pause and rewind live audio from any application on your Mac. Intermission will buffer up to 3 hours of audio, allowing users to skip through any assortment of audio... Read more
Autopano Giga 3.6 - Stitch multiple imag...
Autopano Giga allows you to stitch 2, 20, or 2,000 images. Version 3.0 integrates impressive new features that will definitely make you adopt Autopano Pro or Autopano Giga: Choose between 9... Read more
Airfoil 4.8.7 - Send audio from any app...
Airfoil allows you to send any audio to AirPort Express units, Apple TVs, and even other Macs and PCs, all in sync! It's your audio - everywhere. With Airfoil you can take audio from any... Read more
Microsoft Remote Desktop 8.0.8 - Connect...
With Microsoft Remote Desktop, you can connect to a remote PC and your work resources from almost anywhere. Experience the power of Windows with RemoteFX in a Remote Desktop client designed to help... Read more
xACT 2.30 - Audio compression toolkit. (...
xACT stands for X Aaudio Compression Toolkit, an application that encodes and decodes FLAC, SHN, Monkey’s Audio, TTA, Wavpack, and Apple Lossless files. It also can encode these formats to MP3, AAC... Read more
Firefox 31.0 - Fast, safe Web browser. (...
Firefox for Mac offers a fast, safe Web browsing experience. Browse quickly, securely, and effortlessly. With its industry-leading features, Firefox is the choice of Web development professionals... Read more
Little Snitch 3.3.3 - Alerts you to outg...
Little Snitch gives you control over your private outgoing data. Track background activityAs soon as your computer connects to the Internet, applications often have permission to send any... Read more
Thunderbird 31.0 - Email client from Moz...
As of July 2012, Thunderbird has transitioned to a new governance model, with new features being developed by the broader free software and open source community, and security fixes and improvements... Read more

Latest Forum Discussions

See All

Jacob Jones and the Bigfoot Mystery : Ep...
Jacob Jones and the Bigfoot Mystery : Episode 2 1.0 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0 (iTunes) Description: Jacob Jones is back in Episode 2 of one of Apples 'Best of 2013' games and an App Store... | Read more »
New Trailer For Outcast Odyssey, A New K...
New Trailer For Outcast Odyssey, A New Kind of Card Battler Posted by Jennifer Allen on July 25th, 2014 [ permalink ] Out this Fall is a new kind of card battle game: Outcast Odyssey. | Read more »
Garfield: Survival of the Fattest Coming...
Garfield: Survival of the Fattest Coming to iOS this Fall Posted by Jennifer Allen on July 25th, 2014 [ permalink ] Who loves lasagna? Me. Also everyone’s favorite grumpy fat cat, Garfield. | Read more »
Happy Flock Review
Happy Flock Review By Andrew Fisher on July 25th, 2014 Our Rating: :: HERD IT ALL BEFOREUniversal App - Designed for iPhone and iPad Underneath the gloss of Happy Flock’s visuals is a game of very little substance. It’s cute, but... | Read more »
Square Register Updates Adds Offline Pay...
Square Register Updates Adds Offline Payments Posted by Ellis Spice on July 25th, 2014 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
Looking For Group – Hearthstone’s Curse...
For the first time since its release (which has thankfully been a much shorter window for iPad players than their PC counterparts), Blizzard’s wildly successful Hearthstone: Heroes of Warcraft CCG is sporting some brand new content: the single... | Read more »
Poptile Review
Poptile Review By Jennifer Allen on July 25th, 2014 Our Rating: :: SIMPLY FUNUniversal App - Designed for iPhone and iPad Simple yet a little bit glorious, Poptile is a satisfying entertaining puzzle game with oodles of the ‘one... | Read more »
Modern Combat 5: Blackout Review
Modern Combat 5: Blackout Review By Brittany Vincent on July 25th, 2014 Our Rating: :: LESS QQ, MORE PEW PEWUniversal App - Designed for iPhone and iPad The fifth entry into the blockbuster Modern Combat series is what mobile... | Read more »
Watch and Share Mobile Gameplay Videos W...
Watch and Share Mobile Gameplay Videos With Kamcord Posted by Jennifer Allen on July 25th, 2014 [ permalink ] iPhone App - Designed for the iPhone, compatible with the iPad | Read more »
THE KING OF FIGHTERS '98 (Games)
THE KING OF FIGHTERS '98 1.0 Device: iOS Universal Category: Games Price: $3.99, Version: 1.0 (iTunes) Description: Series’ masterpiece “KOF ’98” finally joins the battle on iPhone! FEATURES:■ The best game balance in the “KOF”... | Read more »

Price Scanner via MacPrices.net

iMacs on sale for $150 off MSRP, $250 off for...
Best Buy has iMacs on sale for up to $160 off MSRP for a limited time. Choose free home shipping or free instant local store pickup (if available). Prices are valid for online orders only, in-store... Read more
Mac minis on sale for $100 off MSRP, starting...
Best Buy has Mac minis on sale for $100 off MSRP. Choose free shipping or free instant local store pickup. Prices are for online orders only, in-store prices may vary: 2.5GHz Mac mini: $499.99 2.3GHz... Read more
Global Tablet Market Grows 11% in Q2/14 Notwi...
Worldwide tablet sales grew 11.0 percent year over year in the second quarter of 2014, with shipments reaching 49.3 million units according to preliminary data from the International Data Corporation... Read more
New iPhone 6 Models to Have Staggered Release...
Digitimes’ Cage Chao and Steve Shen report that according to unnamed sources in Apple’s upstream iPhone supply chain, the new 5.5-inch iPhone will be released several months later than the new 4.7-... Read more
New iOS App Helps People Feel Good About thei...
Mobile shoppers looking for big savings at their favorite stores can turn to the Goodshop app, a new iOS app with the latest coupons and deals at more than 5,000 online stores. In addition to being a... Read more
Save on 5th generation refurbished iPod touch...
The Apple Store has Apple Certified Refurbished 5th generation iPod touches available starting at $149. Apple’s one-year warranty is included with each model, and shipping is free. Many, but not all... Read more
What Should Apple’s Next MacBook Priority Be;...
Stabley Times’ Phil Moore says that after expanding its iMac lineup with a new low end model, Apple’s next Mac hardware decision will be how it wants to approach expanding its MacBook lineup as well... Read more
ArtRage For iPhone Painting App Free During C...
ArtRage for iPhone is currently being offered for free (regularly $1.99) during Comic-Con San Diego #SDCC, July 24-27, in celebration of the upcoming ArtRage 4.5 and other 64-bit versions of the... Read more
With The Apple/IBM Alliance, Is The iPad Now...
Almost since the iPad was rolled out in 2010, and especially after Apple made a 128 GB storage configuration available in 2012, there’s been debate over whether the iPad is a serious tool for... Read more
MacBook Airs on sale starting at $799, free s...
B&H Photo has the new 2014 MacBook Airs on sale for up to $100 off MSRP for a limited time. Shipping is free, and B&H charges NY sales tax only. They also include free copies of Parallels... Read more

Jobs Board

*Apple* Solutions Consultant (ASC) - Apple (...
**Job Summary** The ASC is an Apple employee who serves as an Apple brand ambassador and influencer in a Reseller's store. The ASC's role is to grow Apple Read more
*Apple* Solutions Consultant (ASC) - Apple (...
**Job Summary** The ASC is an Apple employee who serves as an Apple brand ambassador and influencer in a Reseller's store. The ASC's role is to grow Apple Read more
Sr. Project Manager for *Apple* Campus 2 -...
…the design and construction of one building or building components of the New Apple Campus located in Cupertino, CA. They will provide project management oversight for Read more
WW Sales Program Manager, *Apple* Online St...
**Job Summary** Imagine what you could do here. At Apple , great ideas have a way of becoming great products, services, and customer experiences very quickly. Bring Read more
*Apple* Solutions Consultant (ASC) - Apple (...
**Job Summary** The ASC is an Apple employee who serves as an Apple brand ambassador and influencer in a Reseller's store. The ASC's role is to grow Apple Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.