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 object’s 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 object’s 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 recipient’s 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 object’s Name, Address, and Type properties, respectively. The entryID parameter corresponds to an AddressEntry object’s 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 recipient’s Address property. An AddressEntry object’s 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 object’s 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 object’s 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:johndoe@microsoft.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)