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

A Better Finder Rename 10.00b1 - File, p...
A Better Finder Rename is the most complete renaming solution available on the market today. That's why, since 1996, tens of thousands of hobbyists, professionals and businesses depend on A Better... Read more
CrossOver 14.1.6 - Run Windows apps on y...
CrossOver can get your Windows productivity applications and PC games up and running on your Mac quickly and easily. CrossOver runs the Windows software that you need on Mac at home, in the office,... Read more
Printopia 2.1.14 - Share Mac printers wi...
Run Printopia on your Mac to share its printers to any capable iPhone, iPad or iPod Touch. Printopia will also add virtual printers, allowing you to save print-outs to your Mac and send to apps.... Read more
Google Drive 1.24 - File backup and shar...
Google Drive is a place where you can create, share, collaborate, and keep all of your stuff. Whether you're working with a friend on a joint research project, planning a wedding with your fiancé, or... Read more
Chromium 45.0.2454.85 - Fast and stable...
Chromium is an open-source browser project that aims to build a safer, faster, and more stable way for all Internet users to experience the web. Version 45.0.2454.85: Note: Does not contain the "... Read more
OmniFocus 2.2.5 - GTD task manager with...
OmniFocus helps you manage your tasks the way that you want, freeing you to focus your attention on the things that matter to you most. Capturing tasks and ideas is always a keyboard shortcut away in... Read more
iFFmpeg 5.7.1 - Convert multimedia files...
iFFmpeg is a graphical front-end for FFmpeg, a command-line tool used to convert multimedia files between formats. The command line instructions can be very hard to master/understand, so iFFmpeg does... Read more
VOX 2.6 - Music player that supports man...
VOX is a beautiful music player that supports many filetypes. The beauty is in its simplicity, yet behind the minimal exterior lies a powerful music player with a ton of features and support for all... Read more
Box Sync 4.0.6567 - Online synchronizati...
Box Sync gives you a hard-drive in the Cloud for online storage. Note: You must first sign up to use Box. What if the files you need are on your laptop -- but you're on the road with your iPhone? No... Read more
Carbon Copy Cloner 4.1.4 - Easy-to-use b...
Carbon Copy Cloner backups are better than ordinary backups. Suppose the unthinkable happens while you're under deadline to finish a project: your Mac is unresponsive and all you hear is an ominous,... Read more

You Can Play Madfinger Games' Unkil...
Madfinger Games - probably best known for the Dead Trigger series - has officially launched their newest zombie shooter (that isn't called Dead Trigger), named Unkilled. [Read more] | Read more »
KORG iELECTRIBE for iPhone (Music)
KORG iELECTRIBE for iPhone 1.0.1 Device: iOS iPhone Category: Music Price: $9.99, Version: 1.0.1 (iTunes) Description: ** 50% OFF Special Launch Sale - For a Limited Time **The ELECTRIBE reborn in an even smaller form A full-fledged... | Read more »
I am Bread (Games)
I am Bread 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: ‘I am Bread’ is the latest quirky adventure from the creators of 'Surgeon Simulator', Bossa Studios. This isn't the best thing... | Read more »
Rock(s) Rider - HD Edition (Games)
Rock(s) Rider - HD Edition 1.0.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0.0 (iTunes) Description: *** PLEASE NOTE: Compatible with iPhone 4s, iPad 2, iPad mini, iPod touch (5th generation) or newer *** Do you... | Read more »
Rebuild 3: Gangs of Deadsville (Games)
Rebuild 3: Gangs of Deadsville 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: It's been a few years since the zombpocalypse turned the world's cities into graveyards and sent the few... | Read more »
Power Ping Pong (Games)
Power Ping Pong 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: Do you wield your bat with zen-like focus or do your balls of fury give you a killer spin? Table tennis goes mobile with a... | Read more »
Z.O.N.A Project X (Games)
Z.O.N.A Project X 1.00 Device: iOS Universal Category: Games Price: $1.99, Version: 1.00 (iTunes) Description: Z.O.N.A Project X - shooter in the post-apocalyptic world. | Read more »
Trick Shot (Games)
Trick Shot 1.0.6 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0.6 (iTunes) Description: A game where all you have to do is throw a ball into a box, simple? Trick Shot is a minimalist physics puzzler with 90 levels... | Read more »
VoxelCity (Games)
VoxelCity 1.0.2 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0.2 (iTunes) Description: Looking for a new city builder? Tired of social media anti-games with no strategy? Look no further! NO IAP EVER! VoxelCity is a... | Read more »
Goat Simulator MMO Simulator (Games)
Goat Simulator MMO Simulator 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: ** IMPORTANT - SUPPORTED DEVICESiPhone 4S, iPad 2, iPod Touch 5 or better.** Coffee Stain Studios brings next-gen... | Read more »

Price Scanner via MacPrices.net

Near-Office Input Functionality Virtually Any...
Today Logitech introduced the Logitech K380 Multi-Device Bluetooth Keyboard and the Logitech M535 Bluetooth Mouse, giving users the freedom to work on any device, most anywhere. According to... Read more
College Student Deals: Additional $100 off Ma...
Take an additional $100 off all MacBooks and iMacs at Best Buy Online with their College Students Deals Savings, valid through September 4, 2015. Anyone with a valid .EDU email address can take... Read more
Will You Buy An iPad Pro? – The ‘Book Mystiqu...
It looks like we may not have to wait much longer to see what finally materializes as a new, larger-panel iPad (Pro/Plus?) Usually reliable Apple product prognosticator KGI Securities analyst Ming-... Read more
eFileCabinet Announces SMB Document Managemen...
Electronic document management (EDM) eFileCabinet, Inc., a hosted solutions provider for small to medium businesses, has announced that its SecureDrawer and eFileCabinet Online services will be... Read more
WaterField Designs Unveils American-Made, All...
San Francisco’s WaterField Designs today unveiled their all-leather Cozmo 2.0 — an elegant attach laptop bag with carefully-designed features to suit any business environment. The Cozmo 2.0 is... Read more
Apple’s 2015 Back to School promotion: Free B...
Purchase a new Mac or iPad at The Apple Store for Education and take up to $300 off MSRP. All teachers, students, and staff of any educational institution qualify for the discount. Shipping is free,... Read more
128GB MacBook Airs on sale for $100 off MSRP,...
B&H Photo has 11″ & 13″ MacBook Airs with 128GB SSDs on sale for $100 off MSRP. Shipping is free, and B&H charges NY sales tax only: - 11″ 1.6GHz/128GB MacBook Air: $799.99, $100 off MSRP... Read more
13-inch 2.5GHz MacBook Pro (refurbished) avai...
The Apple Store has Apple Certified Refurbished 13″ 2.5GHz MacBook Pros available for $829, or $270 off the cost of new models. Apple’s one-year warranty is standard, and shipping is free: - 13″ 2.... Read more
27-inch 3.2GHz iMac on sale for $1679, save $...
B&H Photo has the 27″ 3.2GHz iMac on sale for $1679.99 including free shipping plus NY sales tax only. Their price is $120 off MSRP. Read more
Apple and Cisco Partner to Deliver Fast-Lane...
Apple and Cisco have announced a partnership to create a “fast lane” for iOS business users by optimizing Cisco networks for iOS devices and apps. The alliance integrates iPhone with Cisco enterprise... Read more

Jobs Board

*Apple* Retail - Multiple Customer Support P...
Job Description: Customer Support Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the Read more
*Apple* Desktop Analyst - KDS Staffing (Unit...
…field and consistent professional recruiting achievement. Job Description: Title: Apple Desktop AnalystPosition Type: Full-time PermanentLocation: White Plains, NYHot Read more
Simply Mac *Apple* Specialist- Repair Techn...
Simply Mac is the greatest premier retailer of Apple products expertise in North America. We're looking for dedicated individuals to provide personalized service and Read more
Simply Mac *Apple* Specialist- Service Repa...
Simply Mac is the greatest premier retailer of Apple products expertise in North America. We're looking for dedicated individuals to provide personalized service and Read more
*Apple* Desktop Analyst - KDS Staffing (Unit...
…field and consistent professional recruiting achievement. Job Description: Title: Apple Desktop AnalystPosition Type: Full-time PermanentLocation: White Plains, NYHot Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.