Do you ever get e-mail messages that were sent to a large number of recipients — perhaps from someone who sends out a newsletter? You might want to be able to e-mail all of the same people, as a group, yourself. You can put all recipients into a group in your Address Book so that you can send messages to the same set of people.

Microsoft Entourage offers only the options, Add Sender to Address Book from a rule, or Add to Address Book when you click on a single name and address, one at a time. There isn't an option for adding multiple recipients anywhere. The following script does it for you. First select the message in question, then run the script.

tell application "Microsoft Entourage"
    display dialog "Enter a name for the group to be made from " & ¬
        "the To recipients of selected messages:" default answer "" ¬
        with icon 1
    set groupName to text returned of result
    display dialog "Do you want the group set to show " & ¬
        "individual addresses or NOT show addresses in messages " & ¬
        "to the group?" buttons {"Cancel", "Show addresses", ¬
        "Don't show"} default button 3 with icon 1
    if button returned of result = "Don't show" then
        set showOnlyName to true
    else
        set showOnlyName to false
    end if
     
    set theGroup to make new group with properties ¬
        {name:groupName, show only name in messages:showOnlyName}
    set selectedMessages to (current messages)
     
    set entryAddresses to {} -- initialize an empty list
    repeat with i from 1 to (count selectedMessages)
        set theMsg to item i of my selectedMessages

        repeat with toRecip in (every recipient of theMsg ¬
            whose recipient type is to recipient)
            set {dName, eAddress} to {display name, address} ¬
                of (address of toRecip)
            if dName ­ "" then
                set nameAddress to "\"" & dName & "\" <" ¬
                    & eAddress & ">"
            else
                set nameAddress to eAddress
            end if
            if {eAddress} is not in entryAddresses then
                make new group entry at theGroup ¬
                    with properties {content:nameAddress} 
                    -- note content syntax!
                set end of entryAddresses to eAddress
            end if
        end repeat
    end repeat
    beep 2
    open theGroup
end tell

The script first opens a dialog box that asks you to type a name for the new group; note that default answer:"" is the way to include a blank text box in display dialog. Check for more options in the display dialog entry in the Standard Additions dictionary. The script then sets the variable groupName to text returned of result (what you type in the text box).

Then a dialog box asks you whether you want the names and e-mail addresses of the group to show. This question corresponds to a similar checkbox you find when you open the window for a group in the Address Book using the UI. The script then sets the variable showOnlyName to true or false depending on the answer.

Then you make the new group, assigning it the variable theGroup, specifying its name and show only name in messages properties with the variables previously assigned for those values.

You get the selected messages and then process each item of the selectedMessages list (each message) in the repeat loop. You can run the script on several messages at once if you want, or just one (current messages is always a list, even if just a single-item list).

Before starting the outer repeat loop, you initialize an empty list entryAddresses, to which you will add entries as you make them. By setting it only once, outside the outer repeat loop, you ensure that duplicate contacts will be avoided for all of the messages being processed.

Within the outer repeat loop (for each message), you now proceed to the inner repeat loop for each to recipient of the message. If you want to include cc recipients as well, simply remove the whose recipient type is to recipient clause.

The recipient class is unusual in that its address property is a record containing both a different address property (a string, namely the actual e-mail address) and a display name property, which might be "" (blank) if not included in the message. Assign the variables eAddress and dName to them, respectively. You then need to check whether the display name is present or missing, since if it is not blank (dName ≠ ""), you include it followed by a space and the e-mail address in < > brackets when assigning the nameAddress variable. If the display name is blank (else), you include only the e-mail address on its own.

Note the extra quotes around dName, if present. This is required in Entourage if the display name happens to contain any punctuation (such as a period after an initial), which would otherwise error further down the script when creating the group entry. It does no harm if there is no punctuation. In that case, you will not even see the quotes around the display name in the UI since they are removed automatically if they are not needed.

Also note that you need to escape literal double quotes with the \ backslash in AppleScript. So when concatenating literal quotes to a variable representing text, namely dName here, that comes out as "\"" & dName & "\"". In the script, the final (outer) closing quote is withheld until the rest of the literal text ( <) that is before the next concatenation has been added: "\"" & dName & "\" <".

You then check to see whether the e-mail address, eAddress, has already been added to the list of entryAddresses. You do not want duplications. You do it this way (checking for eAddress rather than nameAddress) because you don't care if a previous instance did or did not include some version or other of the display name. You do not want to duplicate messages to this person every time in the future even if the current message did so.

If you do not see the e-mail address already in the entryAddresses list, you proceed to make a new group entry, at (in) the group, and add the e-mail address to the list now.

The following is the best and most efficient way to add a new item to a list in AppleScript, and you should always use it.

set end of entryAddresses to eAddress

Concatenating a new, single-item list to the existing list is much slower. It forces AppleScript to make a new copy of the list in memory and to iterate the list as well. Using copy eAddress to end of entryAddresses is less efficient for the same reason.

The dictionary entry for group entry in the Entourage Contact Suite has the following structure:

group entry  n, pl group entries : every group entry

ELEMENTS
contained by groups.

PROPERTIES
content (address, r/o) : address of entry

Check the "type" for its sole content property: address class. If you click the link to address in Macintosh Script Editor, you find the following:

address  n, pl addresses : every address

ELEMENTS
contained by application.

PROPERTIES
display name (Unicode text) : the name used for display
address (string) : the e-mail address

That's the address class with the two properties: address and display name. If you:

get content of every group entry of group "Group Name"

using the name of any existing group you have, you will see that the content of each entry does have the record structure of

{address:"someone@example.com", display name:"Phyllis Harris"}

Therefore, when preparing to make a new group entry at your new group, you might think the syntax ought to be:

make new group entry at theGroup ¬
	with properties {content:{address:eAddress, display name:dName}}

rather than:

make new group entry at theGroup ¬
	with properties {content:nameAddress}

where you made nameAddress text in this format:

set nameAddress to "\"" & dName & "\" <" & eAddress & ">"

In fact, you may think it should be able to get the address property of each recipient of the original message and make that the content for the new group entry, without needing to parse it into its own separate address and display name properties, other than for checking for duplication.

However, this doesn't work in Entourage AppleScript. When making a new group entry, you have to use the text format of Phyllis Harris <someone@example.com>, or simply someone@example.com if there's no display name, rather than the record structure for content of {address:"someone@example.com", display name:"Phyllis Harris"}.

Because this structure has been in place since the advent of Entourage, if it were changed, it would break too many scripts. It is only documented here.