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.

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

OnyX 3.2.4 - Maintenance and optimizatio...
OnyX is a multifunction utility that you can use to verify the startup disk and the structure of its system files, to run miscellaneous maintenance and cleaning tasks, to configure parameters in the... Read more
Opera 43.0.2442.991 - High-performance W...
Opera is a fast and secure browser trusted by millions of users. With the intuitive interface, Speed Dial and visual bookmarks for organizing favorite sites, news feature with fresh, relevant content... Read more
VueScan 9.5.71 - Scanner software with a...
VueScan is a scanning program that works with most high-quality flatbed and film scanners to produce scans that have excellent color fidelity and color balance. VueScan is easy to use, and has... Read more
SpamSieve 2.9.28 - Robust spam filter fo...
SpamSieve is a robust spam filter for major email clients that uses powerful Bayesian spam filtering. SpamSieve understands what your spam looks like in order to block it all, but also learns what... Read more
GarageSale 7.0.7 - Create outstanding eB...
GarageSale is a slick, full-featured client application for the eBay online auction system. Create and manage your auctions with ease. With GarageSale, you can create, edit, track, and manage... Read more
Thunderbird 45.7.1 - Email client from M...
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
GarageSale 7.0.7 - Create outstanding eB...
GarageSale is a slick, full-featured client application for the eBay online auction system. Create and manage your auctions with ease. With GarageSale, you can create, edit, track, and manage... Read more
SpamSieve 2.9.28 - Robust spam filter fo...
SpamSieve is a robust spam filter for major email clients that uses powerful Bayesian spam filtering. SpamSieve understands what your spam looks like in order to block it all, but also learns what... Read more
Thunderbird 45.7.1 - Email client from M...
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
Opera 43.0.2442.991 - High-performance W...
Opera is a fast and secure browser trusted by millions of users. With the intuitive interface, Speed Dial and visual bookmarks for organizing favorite sites, news feature with fresh, relevant content... Read more

Last week on Pocket Gamer
If you’re wondering what’s going on in the wider world of portable gaming, our sister site PocketGamer has you covered. Each week we like to check in on the PG team and see what they’ve been preoccupied with. From the latest on the Nintendo Switch... | Read more »
Mudd Masher arrives this week
Atooi Games, the minds behind Totes the Goat and Mutant Mudds, have a new game in the works -- Mudd Masher. The game, a hybrid of the independent studio's first two titles, is expected to launch this week on March 2. [Read more] | Read more »
The best sales on the App Store this wee...
The App Store has quite an exciting lineup of discount games this week that range across a variety of genres. It's a great opportunity to catch up on some of the premium games you may have been holding off on -- and some you can even grab for free... | Read more »
The best new games we played this week
Ah, here we are again at the close of another busy week. Don't rest too easy, though. We had a lot of great new releases in mobile games this week, and now you're going to have to spend all weekend playing them. That shouldn't be too much of a... | Read more »
Rollercoaster Tycoon Touch Guide: How to...
| Read more »
Rabbids Crazy Rush Guide: How to unlock...
The Rabbids are back in a new endless running adventure, Rabbids Crazy Rush. It's more ridiculous cartoon craziness as you help the little furballs gather enough fuel (soda) to get to the moon. Sure, it's a silly idea, but everyone has dreams --... | Read more »
Tavern Guardians (Games)
Tavern Guardians 1.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: Tavern Guardians is a Hack-and-Slash action game played in the style of a match-three. You can experience high pace action... | Read more »
Slay your way to glory in idle RPG Endle...
It’s a golden age for idle games on the mobile market, and those addictive little clickers have a new best friend. South Korean developer Ekkorr released Endless Frontier last year, and players have been idling away the hours in the company of its... | Read more »
Tiny Striker: World Football Guide - How...
| Read more »
Good news everyone! Futurama: Worlds of...
Futurama is finding a new home on mobile in TinyCo and Fox Interactive's new game, Futurama: Worlds of Tomorrow. They're really doing it up, bringing on board Futurama creator Matt Groening along with the original cast and writers. TinyCo wants... | Read more »

Price Scanner via MacPrices.net

13-inch 2.7GHz Retina MacBook Pro on sale for...
B&H Photo has the 2015 13″ 2.7GHz/128GB Retina Apple MacBook Pro on sale for $150 off MSRP. Shipping is free, and B&H charges NY tax only: - 13″ 2.7GHz/128GB Retina MacBook Pro (MF839LL/A): $... Read more
13-inch 1.6GHz/256GB MacBook Air on sale for...
Newegg has the 13″ 1.6GHz/256GB MacBook Air (MMGG2LL/A) on sale for $1029.99 including free shipping. Their price is $170 off MSRP, and it’s the lowest price available for this model. Choose Newegg... Read more
Apple refurbished Apple TVs available for up...
Apple has Certified Refurbished 32GB and 64GB Apple TVs available for up to $30 off the cost of new models. Apple’s standard one-year warranty is included with each model, and shipping is free: -... Read more
27-inch 3.3GHz 5K iMac on sale for $2099, sav...
B&H Photo has the 27″ 3.3GHz 5K Apple iMac on sale for $2099.99 including free shipping plus NY sales tax only. Their price is $200 off MSRP. Amazon also has the 27″ 3.3GHz 5K iMac on sale for $... Read more
21-inch iMacs on sale for up to $111 off MSRP
B&H Photo has select 21″ Apple iMacs on sale for up to $110 off MSRP, each including free shipping plus NY sales tax only: - 21″ 2.8GHz iMac: $1189 $110 off MSRP - 21″ 1.6GHz iMac: $999 $100 off... Read more
12-inch 1.2GHz Retina MacBooks on sale for $2...
Newegg has the 12″ 1.2GHz Space Gray Retina MacBook (sku MLH82LL/A) on sale for $1349.99 including free shipping. Their price is $250 off MSRP, and it’s the lowest price available for this model.... Read more
13-inch MacBook Airs on sale for $100 off MSR...
B&H Photo has 13″ MacBook Airs on sale for $100 off MSRP. Shipping is free, and B&H charges NY sales tax only: - 13″ 1.6GHz/128GB MacBook Air (MMGF2LL/A): $899 $100 off MSRP - 13″ 1.6GHz/... Read more
9-inch 32GB Silver iPad Pro on sale for $549,...
B&H Photo has the 9.7″ 32GB Silver Apple iPad Pro on sale for $549 for a limited time. Shipping is free, and B&H charges NY sales tax only. Their price is $50 off standard MSRP for this model... Read more
13-inch 2.0GHz Apple MacBook Pros on sale for...
B&H has the non-Touch Bar 13″ 2.0GHz MacBook Pros in stock today and on sale for $100 off MSRP. Shipping is free, and B&H charges NY sales tax only: - 13″ 2.0GHz MacBook Pro Space Gray (... Read more
15-inch Touch Bar MacBook Pros on sale for up...
B&H Photo has the new 2016 15″ Apple Touch Bar MacBook Pros in stock today and on sale for up to $150 off MSRP. Shipping is free, and B&H charges NY sales tax only: - 15″ 2.7GHz Touch Bar... Read more

Jobs Board

*Apple* Solutions Consultant - Apple (United...
# Apple Solutions Consultant Job Number: 55676865 Los Angeles, California, United States Posted: Feb. 22, 2017 Weekly Hours: 40.00 **Job Summary** As an Apple Read more
Programmer/Editor *Apple* Music Dance - App...
# Programmer/Editor Apple Music Dance Job Number: 55565967 Culver City, California, United States Posted: Feb. 23, 2017 Weekly Hours: **Job Summary** Apple Music Read more
Digital Marketing Specialist - *Apple* iClo...
# Digital Marketing Specialist - Apple iCloud Job Number: 54729233 Culver City, California, United States Posted: Feb. 22, 2017 Weekly Hours: 40.00 **Job Summary** Read more
Marketing Specialist, iTunes & *Apple*...
# Marketing Specialist, iTunes & Apple Music Job Number: 55704205 Culver City, California, United States Posted: Feb. 23, 2017 Weekly Hours: 40.00 **Job Summary** Read more
*Apple* Wireless Lead - T-ROC - The Retail O...
…of knowledge in wireless sales and activations to the Beautiful and NEW APPLE Experiencestore within MACYS. THIS role, APPLE Wireless Lead, isbrandnewas MACYS Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.