TweetFollow Us on Twitter

Introduction to AppleScripting Microsoft Entourage

Volume Number: 23 (2007)
Issue Number: 05
Column Tag: Scripting

AppleScript Essentials

Introduction to AppleScripting Microsoft Entourage

by Ben Waldie

For some time now, we have been discussing scripting the Microsoft Office applications, partially in preparation for the forthcoming release of Office 2008, in which Microsoft has announced that Visual Basic macros will no longer be supported. So far, we have explored the AppleScript support in Microsoft Word, Excel, and PowerPoint, three applications that currently (in Office 2004) include Visual Basic macro support. This month, we are going to discuss the fourth major Office application, Entourage, a popular email and project management client.

Unlike the other Office applications, Entourage does not include Visual Basic macro support. So, when Office 2008 is released, there won't be any macros requiring conversion. However, Entourage does possess fairly comprehensive AppleScript support. Using AppleScript, it is possible to manipulate various types of elements in Entourage, including messages, contacts, events, tasks, notes, and more. In this month's column, we will explore ways of manipulating some of these elements. Let's get started.

Working with Messages

Probably the primary elements with which you will want to interact are messages. Using AppleScript, it is possible to create messages, read messages, send messages, move messages from one folder to another, and more.

In Entourage, there are two primary types of messages, incoming and outgoing. While each of these types possesses its own set of properties, both types inherit a number of common properties from the more generic message class.

Creating an Outgoing Message

To create a new outgoing message, use the make command, followed by the class outgoing message, and optionally, properties to be assigned to the message. For example:

set theSubject to "Some Subject"
set theBody to "Some Body"
tell application "Microsoft Entourage"
   make new outgoing message with properties 
{subject:theSubject, content:theBody}
end tell
--> outgoing message id 11285 of application "Microsoft Entourage"

Take note that, when creating a new outgoing message, it will not automatically be visible in Entourage's interface. Regardless, it is created. To make a newly created outgoing message visible in Entourage's interface, the message must be opened. Fortunately, the make command will return as its result a reference to the newly created message. This reference may be placed into a variable, which can then be opened using the open command, as demonstrated below.

set theSubject to "Some Subject"
set theBody to "Some Body"
tell application "Microsoft Entourage"
   set theMessage to make new outgoing message with properties
{subject:theSubject, content:theBody}
   open theMessage
end tell

Adding Recipients to a Message

In the examples that we have discussed above, we have specified certain properties for the outgoing message, which are assigned when the message is created. Specifically, we have specified a subject and a body for the message. However, an outgoing message cannot be sent without first assigning it recipients.

When assigning recipients to a message, each recipient must consist of two bits of information. The first bit of information is the address, and the second is the type of recipient (to, cc, bcc). The address of a recipient is broken down even further, into two more parts - an email address and a display name (i.e. first and last name of the recipient).

To accommodate this, Entourage's AppleScript support includes a recipient class, which possesses an address property and a recipient type property. The value of a recipient's address property translates to the address class in Entourage, which has a display name property and an address property of its own. Put together in AppleScript code, this all translates to the following for each recipient in the list of recipients:

{address:{display name:"RecipientName", 
address:"RecipientEmailAddress"}, 
recipient type:to recipient}

Now, let's put this together to assign recipients as a message is created. The following example code will create an outgoing message in Entourage, addressing it to Ben Waldie, and copying MacTech Editorial, the result of which is shown in figure 1.

set theSubject to "Some Subject"
set theBody to "Some Body"
tell application "Microsoft Entourage"
   set theRecipients to {{address:{display name:"Ben Waldie",
address:"ben@automatedworkflows.com"}, recipient type:to recipient},
{address:{display name:"MacTech Editorial", address:"editorial@mactech.com"},
recipient type:cc recipient}}
   set theMessage to make new outgoing message with properties 
{recipient:theRecipients, subject:theSubject, content:theBody}
   open theMessage
end tell


Figure 1. An Outgoing Message with Recipients

Adding Attachments to an Outgoing Message

Another common task when creating outgoing messages is adding attachments. One or more files may be added to an outgoing message as attachments by providing the paths to those files when the message is created, as follows:

set theSubject to "Some Subject"
set theBody to "Some Body"
set theAttachment to choose file with prompt "Select a file to attach:" without invisibles
tell application "Microsoft Entourage"
   set theRecipients to {{address:{display name:"Ben Waldie", 
address:"ben@automatedworkflows.com"}, recipient type:to recipient}, 
{address:{display name:"MacTech Editorial", 
address:"editorial@mactech.com"}, 
recipient type:cc recipient}}
   set theMessage to make new outgoing message with properties 
{recipient:theRecipients, subject:theSubject, 
content:theBody, attachments:theAttachment}
   open theMessage
end tell

In this case, we have only added a single attachment to an outgoing message. Adding multiple attachments is done in the same manner. Just specify a list of paths, rather than a single path. Figure 2 shows the result of the previous example code.


Figure 2. An Outgoing Message with an Attachment

Sending an Outgoing Message

Once you have created an outgoing message, you will most likely want to send it. Earlier, we discussed opening outgoing messages, since they are not visible by default. Well, if you are going to immediately send an outgoing message after creating it, then you might not need to open it. Regardless, to send a message, use the send command, followed by a list of the messages you want to send. For example:

send theMessage

Please note that, when first sending a message via AppleScript, Entourage will display a dialog notifying the user that a script is attempting to send a message (figure 3). The user must click a Send button before the script can proceed. Keep this in mind, and be prepared for this occurrence.


Figure 3. Entourage's Send Message Warning Dialog

Working with Incoming Messages

So far, we have been discussing ways of working with outgoing messages. Incoming messages possess most of the same properties that outgoing messages possess, so interacting with them is very similar.

To retrieve a list of currently selected incoming messages, reference the selection property of the application. For example:

tell application "Microsoft Entourage"
   selection
end tell
--> {incoming message id 136 of application "Microsoft Entourage"}

Once you have a reference to an incoming message, you can retrieve any of its properties. For example, the following code will retrieve the subject of a selected incoming message.

tell application "Microsoft Entourage"
   set theSelection to selection
   set theCurrentMessage to item 1 of theSelection
   subject of theCurrentMessage
end tell
--> "RE: Meeting Today!"

Forwarding a Message

To forward a message to another recipient, you can use Entourage's forward command. This command requires a reference to a message to be forwarded as its direct parameter. Optional parameters include a to recipient for the forwarded message, and whether the forwarded message's window should be opened in Entourage's interface. For example:

tell application "Microsoft Entourage"
   set theSelection to selection
   set theCurrentMessage to item 1 of theSelection
   forward theCurrentMessage to "ben@automatedworkflows.com" 
with opening window
end tell
--> window "FW: Meeting Today!" of application 
"Microsoft Entourage"

Take note that the result of the forward command in the example code above is a reference to the window of the forwarded message. This is because we specified that the forwarded message should be opened. If we had specified for the message not to be opened, then an outgoing message reference would have been returned instead. For example:

tell application "Microsoft Entourage"
   set theSelection to selection
   set theCurrentMessage to item 1 of theSelection
   forward theCurrentMessage to "ben@automatedworkflows.com" 
without opening window
end tell
--> outgoing message id 11277 of application 
"Microsoft Entourage"

Moving a Message to a Folder

You may have a need to move incoming messages from one folder to another via AppleScript. To do this, you can use the move command. When using this command, you must provide a reference to the message you want to move, along with a reference to the folder into which you would like the message to be moved. For example, the following code would move the currently selected message into a folder called "Some Folder".

tell application "Microsoft Entourage"
   set theSelection to selection
   set theCurrentMessage to item 1 of theSelection
   move theCurrentMessage to folder "Some Folder"
end tell

Keep in mind that since folders have a hierarchy in Entourage, then they must be addressed within this hierarchy via AppleScript. The following example code would move a message into a folder named "Another Folder", which resides inside of a folder named "Some Folder".

tell application "Microsoft Entourage"
   set theSelection to selection
   set theCurrentMessage to item 1 of theSelection
   move theCurrentMessage to folder "Another Folder" 
of folder "Some Folder"
end tell

Working with Contacts

Now that we have discussed ways of interacting with messages in Entourage, let's discuss ways of interacting with other scriptable elements. First, we will take a look at contacts.

To create a new contact in Entourage, use the make command, much in the same way that we discussed creating outgoing messages. For the sake of efficiency, you will probably want to apply properties to the contact as it is created. To do this, use the make command's optional with properties parameter.

The following example code demonstrates how this is done. This particular code will create a contact, complete with a first name, last name, company, job title, business address, business web page address, and email address. Figure 4 shows an example of the newly created contact.

tell application "Microsoft Entourage"
   make new contact with properties 
{first name:"Ben", last name:"Waldie", company:"Automated Workflows, LLC", 
job title:"President", business phone number:"610-935-0652", 
business address:{street address:"116 Cold Stream Road", 
city:"Phoenixville", state:"PA", zip:"19460", country:"USA"}, 
business web page:"http://www.automatedworkflows.com", 
email address:{{label:"Work", contents:"ben@automatedworkflows.com"}}}
end tell
--> contact id 18 of application "Microsoft Entourage"


Figure 4. A Newly Created Contact

Please note that, in the example code above, AppleScript records were used to assign values to certain contact properties. This is because these properties reference classes that contain properties of their own. For example, the business address property of a contact references a value of class postal address. The postal address class possesses street address, city, state, zip, and country properties.

Working with Events

AppleScript may also be used to interact with calendar events in Entourage. Like outgoing messages and contacts, events may be created using the make command. For example, the following code will create a new event for this year's Worldwide Developer's Conference in San Francisco. Figure 5 shows an example of the newly created event.

set theStartDate to date "Monday, June 11, 2007 12:00:00 AM"
set theEndDate to date "Friday, June 15, 2007 11:59:00 PM"
tell application "Microsoft Entourage"
   make new event with properties {subject:"WWDC", 
location:"Moscone West, San Francisco, CA",
content:"Apple's Worldwide Developer's Conference", 
start time:theStartDate, end time:theEndDate}
end tell
--> event id 50 of application "Microsoft Entourage"


Figure 5. A Newly Created Event

In Conclusion

Like the other Microsoft Office applications, Entourage has fairly comprehensive AppleScript support, and we have really only scratched the surface in this month's column. You are encouraged to explore some of the other things that can be done via scripting, such as interacting with tasks, triggering AppleScripts from Entourage rules, and more. Be sure to view Entourage's AppleScript dictionary for a complete list of its AppleScript terminology.

Another great way to get started with scripting Entourage is to download some of the many freeware and shareware AppleScripts for Entourage that have been written by third-party developers, such as Paul Berkowitz. Many of these scripts are available from the ScriptBuilders section of MacScripter.net. http://scriptbuilders.net//

Note to Readers

Many of you who are regular MacTech readers know that I have been writing monthly AppleScript columns for MacTech for several years now. In addition to writing for MacTech, I've also been busy running Automated Workflows, LLC, my AppleScript and workflow automation consulting firm. As my company has grown, so have my commitments. For this reason, I have decided that it is time to begin focusing more on my company. Therefore, this month's column will serve as my final regular MacTech column.

Throughout the years, I have received numerous emails from you, the readers. I want to thank you for your many nice comments and questions along the way. As always, my email inbox will remain open, and you are welcome to continue sending your comments and questions to me in the future at ben@automatedworkflows.com. I will also be attending WWDC 2007, and I hope to have the opportunity to meet some of you there, as well.

For a complete list of my MacTech columns, please be sure to visit the "Archives" section of the MacTech website. You can also find links to all of my MacTech columns, as well as many of my other AppleScript and Automator articles, tips, techniques, and books on my website at http://www.automatedworkflows.com.

Keep scripting!


Ben Waldie is the author of the best selling books "AppleScripting the Finder" and the "Mac OS X Technology Guide to Automator", available from http://www.spiderworks.com, as well as an AppleScript Training CD, available from http://www.vtc.com. Ben is also president of Automated Workflows, LLC, a company 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 ben@automatedworkflows.com.

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

Pro Tools 2022.5 - Professional audio ed...
Pro Tools offers audio professionals superb quality and efficiency through one intuitive, integrated production environment. This high-definition system embodies the latest Digidesign innovations,... Read more
Evernote 10.38.1 - Create searchable not...
Evernote allows you to easily capture information in any environment using whatever device or platform you find most convenient, and makes this information accessible and searchable at anytime, from... Read more
calibre 5.43.0 - Complete e-book library...
Calibre is a complete e-book library manager. Organize your collection, convert your books to multiple formats, and sync with all of your devices. Let Calibre be your multi-tasking digital librarian... Read more
Mellel 5.1.2 - The word processor for sc...
Mellel is the leading word processor for OS X and has been widely considered the industry standard for long form documents since its inception. Mellel focuses on writers and scholars for technical... Read more
FileZilla 3.60.0 - Fast and reliable FTP...
FileZilla (ported from Windows) is a fast and reliable FTP client and server with lots of useful features and an intuitive interface. The FileZilla Client not only supports FTP, but also FTP over TLS... Read more
Parallels Desktop 17.1.3 - Run Windows a...
Parallels allows you to run Windows and Mac applications side by side. Choose your view to make Windows invisible while still using its applications, or keep the familiar Windows background and... Read more
iMazing 2.15.0 - Complete iOS device man...
iMazing is the world’s favourite iOS device manager for Mac and PC. Millions of users every year leverage its powerful capabilities to make the most of their personal or business iPhone and iPad.... Read more
Nitro PDF Pro 13.2.1 - Advanced PDF tool...
Nitro PDF Pro allows users to edit PDF's easily. Add text, images and signatures. Fill out PDF forms. Merge or split PDF documents. Reorder and delete pages. Create fillable forms and tables of... Read more
Nitro PDF Pro Essentials 13.2.1 - Edit a...
Nitro PDF Pro Essentials allows users to easily edit PDF's. Add text, images and signatures. Fill out PDF forms. Merge or split PDF documents. Reorder and delete pages. Even correct text and edit... Read more
Adobe InDesign 17.3 - Professional print...
InDesign is available as part of Adobe Creative Cloud for as little as $20.99/month (or $9.99/month if you're a previous InDesign customer). Adobe InDesign is part of Creative Cloud. That means you... Read more

Latest Forum Discussions

See All

Help TikTok Pool Guy, I Need You – The T...
It’s official! The video podcast is back for all you Patreon supporters. Turns out the answer was right in front of us all along: Zoom. Yes, Zoom! Duh! I don’t know why we didn’t think to try that before. Anyhoo, this week’s show is stuffed to the... | Read more »
TouchArcade Game of the Week: ‘Streets o...
It was a stacked week of great new mobile game releases, and it was a really hard week to pick just one for the Game of the Week. It seems like that’s been the case a lot lately, which just means that us mobile gamers are eating quite well as of... | Read more »
SwitchArcade Round-Up: ‘Pac-Man Museum+’...
Hello gentle readers, and welcome to the SwitchArcade Round-Up for May 27th, 2022. In today’s article, we’ve got even more new releases than yesterday to look at. Pac-Man Museum+, Kao the Kangaroo, Remote Life, and Arcade Spirits: The New... | Read more »
Steam Deck Update Reduces Fan Noise, Add...
Today, Valve pushed out another major update for SteamOS on Steam Deck. This update focuses on reducing fan noise with some useful features finally implemented. If you missed our review, see what Jared thought of it at launch here. | Read more »
Pro Darts 2022+ Is Out Now on Apple Arca...
As revealed before, Pro Darts 2022+ () from iWare Designs has gone live on Apple Arcade today as the final May 2022 addition on the service. Pro Darts 2022+ is from the developers who brought us Pro Snooker & Pool 2022+. The App Store version... | Read more »
Strategy Game ‘SD Gundam G Generation Et...
Bandai Namco Entertainment just announced a brand new Gundam strategy game titled SD Gundam G Generation Eternal. SD Gundam G Generation Eternal is a free to play game for iOS and Android that lets you collect your favorite Mobile Suits from the... | Read more »
‘Genshin Impact’ Version 2.7 Pre-Install...
Genshin Impact (Free) version 2.7 update finally releases next week across all platforms following a bit of a delay. Developer HoYoverse previously showcased Yelan in a new character trailer with details for the update being revealed a little while... | Read more »
‘Delete After Reading’ is a New Genre-Mi...
Back in October of 2020, developer Patrones & Escondites released a very unique titled called Unmemory. It’s one part interactive fiction, one part puzzle game, and multiple parts escape room or alternate reality game. Its back-of-the-box pitch... | Read more »
‘Jurassic World Primal Ops’ is a Hero Co...
Did you know that there’s a new Jurassic World movie coming out in just a couple of weeks? Chances are that the movie’s marketing machine has beaten you over the head with that information already, but did you know there’s also a Jurassic World... | Read more »
SwitchArcade Round-Up: ‘Biomotor Unitron...
Hello gentle readers, and welcome to the SwitchArcade Round-Up for May 26th, 2022. The day is Thursday, and that means we’ve got a bunch of new releases to check out. Jumping into the past, we’ve got Biomotor Unitron and Arcade Archives Flipull,... | Read more »

Price Scanner via MacPrices.net

Memorial Day Apple iPad Sale: $30 off 9th-gen...
Apple reseller Expercom is offering a $30 discount on all 9th-generation 10.2″ iPads and a $75 discount on all 11″ M1 iPad Pros through June 6th as part of their Memorial Day Sale. Prices start at $... Read more
Memorial Day Weekend Savings: MagSafe accesso...
Amazon has Apple MagSafe Chargers and Apple’s MagSafe Battery on sale for up to $20 off MSRP as part of their Memorial Day Weekend Sale sale. Shipping is free. Amazon’s sale prices are among the... Read more
Best Memorial Day Weekend MacBook Deal: Get t...
Other World Computing has Apple refurbished, factory-sealed, current-generation 13″ Space Gray M1 MacBook Pros on sale for $420-$500 off Apple’s MSRP, starting at only $879. Their prices are the... Read more
Memorial Day Weekend iPhone Sale: $250 off iP...
As part of their Memorial Day Weekend sale, Xfinity Mobile is offering any new Apple iPhone 13, or the 64GB iPhone 12, for $250 off MSRP for customers switching to Xfinity Mobile and opening a new... Read more
Memorial Day Weekend iPhone Sale: Free $300 g...
Memorial Day Weekend iPhone sales are now live at Verizon’s low-cost wireless cell service, Visible. They will include a free $300 gift card with the purchase of a new 2022 iPhone 13 Pro Max, 13 Pro... Read more
In stock today: 13″ M1 MacBook Air for $899,...
B&H has Apple’s base 13″ M1 MacBook Air (Space Gray) in stock and on sale today for $100 off MSRP, only $899. Free 1-2 day shipping is available to most addresses in the US: 8-Core M1 Apple... Read more
In stock today: Open-box 16″ MacBook Pro with...
Having trouble finding a 16″ M1 Pro MacBook Pro to buy? QuickShip Electronics has open-box return 16″ M1 Pro MacBook Pros in stock and on sale for $500 off MSRP on their eBay store right now, each... Read more
16″ MacBook Pro with Apple M1 Pro CPU in stoc...
Stock of Apple’s 16″ MacBook Pro can be hard to find at resellers today. However, Apple reseller Expercom is reporting stock of the Silver 16″ MacBook Pro with a 10-Core M1 Pro CPU and 512GB SSD... Read more
Amazon has select 13″ M1 MacBook Airs on sale...
Amazon has select Apple 13″ M1 MacBook Airs on sale for $100 off MSRP today, only $899. Amazon does not have stock of these MacBooks, but they are available for order at the discounted price. The... Read more
Deal Alert! 14″ 10-Core M1 Pro MacBook Pros a...
Amazon has 14″ MacBook Pros with a 10-Core M1 Pro CPUs on sale today for $2249.99 shipped. That’s $250 off Apple’s MSRP. Amazon’s prices are the lowest currently available for 10-Core 14″ MacBook... Read more

Jobs Board

Sr. Strategic Marketing Programs Manager - *...
The Sr. Strategic Marketing Programs Manager - Apple will be focused on helping SHI tell a compelling and exciting story around its partnership with Apple Read more
*Apple* Engineering Specialist - General Dyn...
…IT Service Delivery solutions to SEC. Currently, we are seeking an Apple Engineering Specialist in Washington, DC The responsibilities for candidates in this Read more
*Apple* Engineering Specialist - General Dyn...
…IT Service Delivery solutions to SEC. Currently, we are seeking an Apple Engineering Specialist in Washington, DC The responsibilities for candidates in this Read more
Sephora Beauty Advisor - *Apple* Blossom Ma...
Sephora Beauty Advisor - Apple Blossom Mall Location:Winchester, VA, United States (https://jobs.jcp.com/jobs/location/191170/winchester-va-united-states) - Apple Read more
Omnichannel Associate - *Apple* Blossom Mal...
Omnichannel Associate - Apple Blossom Mall Location:Winchester, VA, United States (https://jobs.jcp.com/jobs/location/191170/winchester-va-united-states) - Apple Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.