Create and send an outgoing message

You can make a very automated message process. If you have to send documents as e-mail attachments everyday, and no special customized text message needs to be written each time, you can write a script to send it all off without interruptions of any kind. You make an outgoing message and send it off without bringing Microsoft Entourage to the front — just stay in whatever application you're in.

If you look in the Entourage dictionary, you'll see that recipient is an element, not a property, of message (and of its subclasses outgoing message and incoming message). That makes sense, since you can have several recipients (of all types, including to recipient, cc recipient, and bcc recipient).

When you want to get the recipients of a message (incoming or sent, for example), that's how you go about it: every recipient of theMsg. Then you delve into the recipient properties to get the email address property and any display name.

You'd expect that when making a new outgoing message, you'd have to make each recipient at the new message just after making it — the typical process for creating elements at an object. However, it can't be done with outgoing message. The reason is that once a message (as opposed to a draft window) is made, it's encoded for the Internet, and its internal structure cannot be modified. However, the developers again have implemented a coercion — another "putative" recipient property, just like the putative attachment property in the previous topic.

Only this time it's essential: it's not an alternative method, it's the only method. And it's not documented. Once again, it is only available at inception, when calling make new outgoing message with properties.

Both properties — address, recipient type — listed under the recipient class in the dictionary are available. The address property's type is the address class. This in turn has a different address (text) property — the actual e-mail address — plus a display name text property.

If you are just sending mail to a single to recipient type, you can omit a lot of the specifications, taking advantage of the fact that to recipient is the default type for the recipient type property. You can also use a Display Name <eaddress@domain> shorthand (< > angle brackets around the e-mail address) instead of the more complex recipient record structure. There is this undocumented coercion:

tell application "Microsoft Entourage"
	launch -- in background
	set theMsg to make new outgoing message with properties ¬
		{subject:"Today's File", content:¬
			"Please find today's .pdf file attached.", recipient:¬
			"Phyllis  Harris <phyllisharris@northwindtraders.com>",¬ 
				attachment:alias filePath}
	send theMsg
end tell

Note the first line: launch. If Entourage is already open in the background, this will do nothing. If Entourage is not open, this will launch it without bringing it to the front, as would happen if you omitted this line. (It's part of the AppleScript language, not Entourage, and works the same way for every application.)

Note the simple recipient property value. Because the script doesn't specify where to make it at, it does so in the local Drafts folder, which is the default location, using the default account. (These properties can all be specified otherwise, if you want.) The file (alias filePath) in the attachment property depends on whether you included the previous code to Microsoft Word, Excel, or PowerPoint to store the path of the saved front document as the variable filePath.

The last line sends the message.

But the full syntax for recipient lets you specify as many recipients as you want, of whichever recipient types (to recipient, cc recipient, bcc recipient) you want, by setting a list (in {} list braces) of all the recipients to the "putative" recipient property. You must also use record braces, which look the same, for each recipient. This is because each one is a record (containing address and recipient type properties) where each address is also a record (containing address and display name properties). You therefore use a lot of braces, as follows:

tell application "Microsoft Entourage"
	launch
	set theMsg to make new outgoing message with properties ¬
		{subject:"Today's File", content:¬
		"Please find today's .pdf file attached.", recipient:¬
		{{address:{address:"phyllisharris@northwindtrader.com", display name:¬
			"Phyllis Harris"}, recipient type:to recipient}, {address:¬
			{address:"ellenadams@northwindtrader.com", display name:¬
				"Ellen Adams"}, recipient type:cc recipient}, ¬
			{address:{address:"juncao@northwindtrader.com", display name:¬
				"Jun Cao"}, recipient type:¬
			bcc recipient}}, attachment:alias filePath}
	send theMsg
end tell

That's just one recipient per type.You can include as many as you want in the list. You can omit the recipient type property if it's a to recipient type, and you can omit the display name. When you write your own scripts, you can ignore the line continuation marks and short lines used here so that you won't get line-end errors if you copy and paste from an online source. Any script editor will wrap long lines as needed.

Once again, the filePath variable in the attachment property depends on whether you included the previous code to Word, Excel, or PowerPoint to store the path of the saved front document as this variable filePath.

Just save the whole script, including the other Microsoft Office application and Entourage code, in the system Script menu, and select it with your daily document in front. Then it's sent to all of those recipients without any activity or disturbance in your front application. You can also add a line of code to the other Office application's block to close the active document, saving yes, if you want.

When you first try to run this script or any other that sends a message, you will get a warning: an external application is trying to send mail. Click to allow it, and if you are going to be doing much scripting of Entourage, also click to not warn you again. You can also go into Entourage Security Preferences using the UI and turn off security warnings about external applications trying to send mail, and trying to access the Address Book. You receive these warnings when trying to run scripts because Entourage considers scripts to be the same thing as "external applications."

Create an outgoing message using more properties

In learning how to make a new message, the discussion has been mostly concerned with recipients because that is the challenging part. There are a great many other properties that can be set by script — in fact, everything that you can do in the UI, and more.

For example, you might want to specify a different e-mail account than your default account.

There is no generic account class, so you need to specify whether it is a POP account, IMAP account, Hotmail account, or Exchange account. Entourage is a database-based application, so virtually everything in it has a unique ID, and all references to elements (items) resolve to an ID reference, even accounts (for example, POP account id 1, IMAP account id 2,and so on).

But you won't usually know those. You can refer to almost everything in Entourage by its name, by its index if you know it, by its ID, or by a whose filter. The name of an account is not its e-mail address (unless that's how you named it, which many people do), but the name you assigned it in Tools > Accounts > Mail. So usually you will refer to it by name as POP account My Account, with My Account representing the name you gave it.

The default signature that you use for that account will appear automatically in the message, so don't add it to the message content or it will appear twice. If you want to change the signature for this message, you need to change the default signature type and default signature choice of the account first (or to none signature type and add the text you want to the message content), and then change it back after you make the message.

The generic subclass outgoing message is contained by the message class, and it inherits a few read-only properties that are appropriate only for (your own) messages after they are sent, such as forwarded, redirected, replied to, and resent. Don't set them for a new message, even though most read-only properties can actually be set at inception if you really need to.

The connection action property is something that usually applies only to incoming POP messages. Don't set that for a new message either. The edited property is really read-only and can't be set by script.

The color property is deprecated. Don't try to set it; it's been replaced by category, and each category has a color property that can be set. The category property shown here is a list of categories {category "Work", category "Personal"} since messages and other objects can have more than one category (the first one listed is primary and sets the color). Or, it can be an empty list {} for no categories: there is no category None. The default is {}, which does not need to be set.

Normally you will not set source, but you would if trying to duplicate another message (with perhaps a few differences that you set separately). The source property is the entire structured message text, parts, attachments, and headers. You wouldn't normally try to script headers either. Let them be formed automatically.

All other properties can be set. The has html property could be set to true at inception — the default is false — but that just determines that your default HTML font and size will be used. Entourage does not have any way to script formatted text, and setting the has html property to true removes carriage returns from the message content, so don't use it. Use the properties marked in the dictionary as read-write.

If you don't specify where to make the message, it gets made at your Drafts folder. The alternate location that you might prefer to specify would be the Outbox. Here's a typical example:

tell application "Microsoft Entourage"
	-- add carriage return before signature used for the account
	set theBody to "Some long text here. As long as you want." ¬
		& return & return
	set theMsg to make new outgoing message at outbox folder ¬
		with properties {account:POP account "My Account", ¬
			subject:"My New Message", content: theBody, ¬
			recipient:"Phyllis Harris <phyllisharris@northwindtrader.com", ¬
			flagged:true, priority:high, category:{category "Work"}}
end tell