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

Day One 4.15.3 - Maintain a daily journa...
Day One is an easy, great-looking way to use a journal / diary / text-logging application. Day One is well designed and extremely focused to encourage you to write more through quick Menu Bar entry,... Read more
Backblaze 7.0.1.450 - Online backup serv...
Backblaze is an online backup service designed from the ground-up for the Mac. With unlimited storage available for $6 per month, as well as a free 15-day trial, peace of mind is within reach with... Read more
Visual Studio Code 1.47.0 - Cross-platfo...
Visual Studio Code provides developers with a new choice of developer tool that combines the simplicity and streamlined experience of a code editor with the best of what developers need for their... Read more
Apple Pages 10.1 - Apple's word pro...
Apple Pages is a powerful word processor that gives you everything you need to create documents that look beautiful. And read beautifully. It lets you work seamlessly between Mac and iOS devices, and... Read more
Shimo 5.0.2 - VPN client for everyone.
Shimo is the most versatile VPN client for OS X and it enables really everybody to master secure network. It supports more protocols than any other VPN application out there! CiscoVPN, AnyConnect,... Read more
Yasu 6.0.1 - System maintenance app.
Note: Yasu is not being sold anymore and is listed only for people who had purchased it in the past. Yasu was created with system administrators who service large groups of workstations in mind, Yasu... Read more
Keynote 10.1 - Apple's presentation...
Easily create gorgeous presentations with the all-new Keynote, featuring powerful yet easy-to-use tools and dazzling effects that will make you a very hard act to follow. The Theme Chooser lets you... Read more
Numbers 10.1 - Apple's spreadsheet...
With Apple Numbers, sophisticated spreadsheets are just the start. The whole sheet is your canvas. Just add dramatic interactive charts, tables, and images that paint a revealing picture of your data... Read more
Capture One 13.1.1.24 - RAW workflow sof...
Capture One is a professional RAW converter offering you ultimate image quality with accurate colors and incredible detail from more than 400 high-end cameras -- straight out of the box. It offers... Read more
Alfred 4.1 - Quick launcher for apps and...
Alfred is an award-winning productivity application for OS X. Alfred saves you time when you search for files online or on your Mac. Be more productive with hotkeys, keywords, and file actions at... Read more

Latest Forum Discussions

See All

Marvel Duel, NetEase's promising ca...
Marvel Duel, NetEase's collectable card battler, has now opened for pre-registration in Thailand, Indonesia, Malaysia, and the Philippines. [Read more] | Read more »
PUBG Mobile teams up with Yamaha for a l...
PUBG Mobile has had various collaborations with various companies since it first burst onto the scene. The latest sees the popular battle royale title teaming up with vehicle and marine products company Yamaha, meaning players can take one of... | Read more »
Marvel Super War launches its third seas...
Marvel Super War, NetEase's popular MOBA, has kicked off its third season today, introducing its Zone Invasion beta and an all-new playable superhero. [Read more] | Read more »
Brave Dungeon, Unlock Games' idle-R...
Brave Dungeon, Unlock Games' idle-RPG and auto chess title, has been downloaded over 1 million times since it launched last week. To commemorate reaching this milestone the developers have decided to host a series of in-game events. [Read more] | Read more »
Clash Royale: The Road to Legendary Aren...
Supercell recently celebrated its 10th anniversary and their best title, Clash Royale, is as good as it's ever been. Even for lapsed players, returning to the game is as easy as can be. If you want to join us in picking the game back up, we've put... | Read more »
Steam Link Spotlight - Disco Elysium
Steam Link Spotlight is a feature where we look at PC games that play exceptionally well using the Steam Link app. Our last entry was Signs of the Sojourner Read about how it plays using Steam Link over here. | Read more »
Distract Yourself With These Great Mobil...
There’s a lot going on right now, and I don’t really feel like trying to write some kind of pithy intro for it. All I’ll say is lots of people have been coming together and helping each other in small ways, and I’m choosing to focus on that as I... | Read more »
Pokemon Go's July Community Day wil...
Pokemon Go developers have announced the details concerning the upcoming Gastly Community Day. This particular event was selected by the players of the game after the Gas Pokemon came in second place after a poll that decided which Pokemon would... | Read more »
Clash Royale: The Road to Legendary Aren...
Supercell recently celebrated its 10th anniversary and their best title, Clash Royale, is as good as it's ever been. Even for lapsed players, returning to the game is as easy as can be. If you want to join us in picking the game back up, we've put... | Read more »
Detective Di is a point-and-click murder...
Detective Di is a point-and-click murder mystery set in Tang Dynasty-era China. You'll take on the role of China's best-known investigator, Di Renjie, as he solves a series of grisly murders that will ultimately lead him on a collision course with... | Read more »

Price Scanner via MacPrices.net

Weekend Sale: Woot offers clearance MacBook,...
Amazon-owned Woot is blowing out a wide range of MacBooks, MacBook Airs, and MacBook Pros starting at only $389. All models are open-box returns, and according to Woot, “these MacBooks are in New-... Read more
Apple’s 2020 Mac minis on sale for up to $100...
B&H Photo has Apple’s 2020 Mac minis on sale today for $40-$100 off MSRP, each including free expedited delivery for many US addresses. These are the same Mac minis sold by Apple in their retail... Read more
Apple restocks refurbished 10.5″ iPad Airs fo...
Apple has restocked 10.5″ WiFI iPad Airs models for up to $100 off MSRP, Certified Refurbished. Each iPad comes with Apple’s standard one-year warranty and includes a new outer case. Shipping is free... Read more
B&H Photo offers $200-$300 discounts on A...
B&H Photo has new 16″ MacBook Pros on sale today for $200-$300 off Apple’s MSRP, starting at $2149. Expedited shipping is free to many addresses in the US: – 2019 16″ 2.6GHz 6-Core MacBook Pro... Read more
Clearance 2019 15″ MacBook Pros on sale today...
Amazon-owned Woot is blowing out Apple refurbished, clearance 2019 15″ MacBook Pros starting at only $1579 and up to $950 off Apple’s original MSRP. According to Woot, “These MacBooks are Refurbished... Read more
Apple Refurbished iMac Pros available for $35...
Amazon-owned Woot is selling Apple refurbished 27″ 3.2GHz 8-Core iMac Pros for $3599.99 shipped. That’s $1400 off Apple’s original MSRP for this model. According to Woot, these iMac Pros are “Factory... Read more
Clearance 2019 13″ 2.4GHz/256GB MacBook Pro o...
B&H Photo has dropped their price on the clearance 2019 13″ 2.4GHz/256GB Quad-Core Silver MacBook Pro by $500 off Apple’s original MSRP to a new low of only $1299. Expedited shipping is free to... Read more
$219 Apple AirPods Pro are back at Verizon, s...
Verizon has Apple AirPods Pro on sale again for a limited time for $219.99 on their online store. Their price is $30 off Apple’s MSRP, and it’s the lowest price we’ve seen for AirPods Pro. Available... Read more
Apple’s $779 13″ MacBook Air deal returns to...
Apple has clearance, Certified Refurbished, 2019 13″ MacBook Airs available again starting at $779. Each MacBook features a new outer case, comes with a standard Apple one-year warranty, and is... Read more
$200 13″ MacBook Pro discounts are back at Am...
Amazon has 2020 13″ 2.0GHz MacBook Pros on sale again today for $150-$200 off Apple’s MSRP. Shipping is free. Be sure to purchase the MacBook Pro from Amazon, rather than a third-party seller, and... Read more

Jobs Board

Geek Squad Advanced Repair *Apple* Professi...
**769390BR** **Job Title:** Geek Squad Advanced Repair Apple Professional **Job Category:** Store Associates **Store Number or Department:** 000580-Reading-Store Read more
Executive Team Leader GM Sales (Assistant Man...
…(Assistant Manager General Merchandise and Operations) - Apple Valley, CaliforniaApply NowJob ID:R0000082364job family:Store Managementschedule:Full Read more
Executive Team Leader Assets Protection (Assi...
…Assets Protection (Assistant Manager Loss Prevention) - Apple Valley, CaliforniaApply NowJob ID:R0000082365job family:Store Managementschedule:Full Read more
*Apple* Computing Sales Professional - Best...
**768543BR** **Job Title:** Apple Computing Sales Professional **Job Category:** Store Associates **Store Number or Department:** 002509-Riverdale-Store **Job Read more
Product Manager, *Apple* Commercial Sales -...
Product Manager, Apple Commercial Sales Austin, TX, US Requisition Number:77652 As an Apple Product Manager for the Commercial Sales team at Insight, you Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.