Add Method (Recipients Collection)

Article
08/21/2009

Add Method (Recipients Collection)

The Add method creates and returns a new Recipient object in the Recipients collection.

Syntax

Set objRecipient = objRecipColl.Add( [name] [, address**] [, type] [, entryID] )**

objRecipient

On successful return, represents the new Recipient object added to the collection.

objRecipColl

Required. The Recipients collection object.

name

Optional. String. The display name of the recipient. When this parameter is not present, the new Recipient objects Name property is set to an empty string. The name parameter is ignored if the entryID parameter is supplied.

address

Optional. String. The full messaging address of the recipient. When this parameter is not present, the new Recipient objects Address property is set to an empty string. The address parameter is ignored if the entryID parameter is supplied.

type

Optional. Long. The recipient type; the initial value for the new recipients Type property. The following values are valid:

Recipient type	Value	Description
CdoTo	1	The recipient is on the To line (default).
CdoCc	2	The recipient is on the Cc line.
CdoBcc	3	The recipient is on the Bcc line.

The type parameter applies whether the entryID parameter is furnished or not.

entryID

Optional. String. The unique identifier of a valid AddressEntry object for this recipient. No default value is supplied for the entryID parameter. When it is present, the name and address parameters are not used. When it is not present, the method uses the name, address, and type parameters to define the recipient.

Remarks

The name, address, and type parameters correspond to the Recipient objects Name, Address, and Type properties, respectively. The entryID parameter corresponds to an AddressEntry objects ID property. When the entryID parameter is present, the name and address parameters are not used.

The address parameter, if set, must contain a full address, such as that contained in the recipients Address property. An AddressEntry objects Address property is not a full address because it does not contain the address type information found in the AddressEntry object's Type property. If the user you are adding is represented by an AddressEntry object, such as is returned by the Session objects CurrentUser property, you must concatenate its Type and Address properties with a connecting colon to construct the full address.

When no parameters are present, an empty Recipient object is created.

The DisplayType property of the new Recipient object is set by the address book provider to either CdoUser or CdoDistList, depending on which kind of recipient is being added. The DisplayType property is read-only and cannot subsequently be changed.

Call the Resolve method after you add a recipient. After the recipient is resolved, you can access the child AddressEntry object through the Recipient objects AddressEntry property.

The Index property of the new Recipient object equals the new Count property of the Recipients collection.

The new recipient is saved in the MAPI system when you Update or Send the parent Message object.

Example

This code fragment adds three recipients to a message. The address for the first recipient is resolved using the display name. The second recipient is a custom address, so the Resolve operation does not modify it. The third recipient is taken from an existing valid AddressEntry object. The Resolve operation is not needed for this recipient.

' from the sample function "Using Addresses"
' add 3 recipient objects to a valid message object

' 1. look up entry in address book
Set objOneRecip = objNewMessage.Recipients.Add(Name:=strName, _
                                               Type:=CdoTo)
If objOneRecip Is Nothing Then
    MsgBox "Unable to add recipient using name and type"
    Exit Function
End If
objOneRecip.Resolve ' find its full address in address book

' 2. add a custom recipient
Set objOneRecip = objNewMessage.Recipients.Add( _
                             Address:="SMTP:user@example.com", _
                             Type:=CdoTo)
If objOneRecip Is Nothing Then
    MsgBox "Unable to add recipient using custom address"
    Exit Function
End If
objOneRecip.Resolve ' make it an object and give it an entry ID

' 3. add a valid address entry object, such as Message.Sender
' assume valid address entry ID from an existing message
Set objOneRecip = objNewMessage.Recipients.Add( _
                                              entryID:=strAddrEntryID)
'     or .Add( , , , strAddrEntryID) if you can't use named parameters
If objOneRecip Is Nothing Then
    MsgBox "Unable to add existing AddressEntry using ID"
    Exit Function
End If

objNewMessage.Text = "expect 3 different recipients"
MsgBox ("Count = " & objNewMessage.Recipients.Count)

Add Method (Recipients Collection)