Add Method (CDONTS Recipients Collection)

Article
08/21/2009

Add Method (CDONTS Recipients Collection)

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

Syntax

        Set
         objRecip = collRecips.Add( [name] [, address] [, type] )

objRecip

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

collRecips

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.

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.

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.

Remarks

The name, address, and type parameters correspond to the Recipient object's Name, Address, and Type properties, respectively.

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

The new recipient is saved in persistent storage when you call the Send method on the Message object containing the Recipients collection.

The Add method returns CdoE_NO_ACCESS when called on a message in the Inbox.

The CDO for NTS Library does not permit any modifications to messages in the Inbox, other than deleting the entire message. Prohibited modifications include adding, deleting, or modifying any attachment; adding, deleting, or modifying any recipient; and modifying any message property, even one with read/write access.

Example

This code fragment adds a recipient to a message using information from an existing valid AddressEntry object

' from the sample function "Using Addresses"
' assume valid address entry ID from an existing message
Set objRecip = objNewMessage.Recipients.Add(type:=CdoTo, _
                                            name:=objAdrEnt.Name)
objRecip.Address = objAddrEnt.Type & ":" & objAddrEnt.Address
   ' ** the preceding line is not strictly necessary with CDO for NTS,
   ' ** but it allows this code to run with CDO for Exchange, where
   ' ** Recipient.Address requires a FULL address concatenated from
   ' ** AddressEntry.Type, ":", and AddressEntry.Address
If objRecip Is Nothing Then
    MsgBox "Unable to add existing AddressEntry using ID"
    Exit Function
End If

objNewMessage.Text = "Expect 1 recipient."
MsgBox ("Count = " & objNewMessage.Recipients.Count)

Add Method (CDONTS Recipients Collection)