Using Addresses

In general, MAPI supports two kinds of addressing:

Addresses that the MAPI system looks up for you in your address book, based on a display name that you supply
Addresses that represent custom addresses, that are used as supplied without lookup

The CDO Library supports both kinds of addresses with its Recipient object. To look up an address for a name, you supply the Name property only. To use custom addresses, you supply the full address in the Address property.

The address book can be thought of as a database in persistent storage, managed by the MAPI system, that contains valid addressing information that is associated with a display name. The display name represents the way that a person's name might be displayed for your application users, using that person's full name, rather than the e-mail address that the messaging system uses to transmit the message. For example, the display name "John Doe" could be mapped to the e-mail address "johnd@company.com".

In contrast to the address book, the objects that you create with the CDO Library are temporary objects that reside in memory. When you fill in the Recipient object's Name property with a display name, you must then resolve the address. To resolve the address means that you ask the MAPI system to look up the display name in the database and supply the corresponding address. When the display name is ambiguous, or can match more than one entry in the address book, the MAPI system prompts the user to select from a list of possible matching names.

The Recipient object's Name property represents the display name. Call the Recipient object's Resolve method to resolve the display name.

After the Recipient object is resolved, it has a child AddressEntry object that contains a copy of the valid addressing information from the database. The child AddressEntry object is accessible from the Recipient object's AddressEntry property. The Recipient and AddressEntry object properties are related as follows:

CDO Library object and property	MAPI property	Description
Recipient.Address	Combination of PR_ADDRTYPE and PR_EMAIL_ADDRESS	Full address; AddressEntry object's Type and Address properties
Recipient.Name	PR_DISPLAY_NAME	Display name
Recipient.AddressEntry.Address	PR_EMAIL_ADDRESS	E-mail address
Recipient.AddressEntry.ID	PR_ENTRYID	AddressEntry object's unique identifier
Recipient.AddressEntry.Name	PR_DISPLAY_NAME	Display name
Recipient.AddressEntry.Type	PR_ADDRTYPE	E-mail type

The Recipient object's Address property represents a full address, that is, the combination of address type and e-mail address that MAPI uses to send a message. The full address represents information that appears in the AddressEntry object's Address and Type properties.

You can also supply a complete recipient address. By manipulating the address yourself, you direct the MAPI system to send the message to the full address that you supply without using the database. In this case, you must also supply the display name. When you supply a custom address, the Recipient object's Address property must use the following syntax:

AddressType:AddressValue

There is also a third method of working with addresses. You can directly obtain and use the Recipient object's child AddressEntry object from messages that have already been successfully sent through the messaging system.

For example, to reply to a message, you can use the Message object's Sender property to get a valid AddressEntry object. When you work with valid AddressEntry objects, you do not have to call the Resolve method.

Note When you use existing AddressEntry objects, do not try to modify them. In general, do not write directly to the Recipient object's child AddressEntry object properties.

In summary, you can provide addressing information in three different ways:

Obtain the correct addressing information for a known display name. Set the Recipient object's Name property and call its Resolve method. You can optionally request that Resolve display a dialog box.
Create a custom address. Set the Recipient object's Address property, using the correct syntax as described earlier, with the colon character (:) separating the address type from the address, and call the Resolve method. You need Resolve even though you have supplied the address, because it must be made into an object and given an entry identifier.
Use an existing valid address entry, such as the Message object's Sender property, when you are replying to a message. Set the Recipient object's AddressEntry property to an existing AddressEntry object that is known to be valid. You do not need to call the Resolve method.

The following code fragment demonstrates these three kinds of addresses:

' Function: Util_UsingAddresses 
' Purpose:  Set addresses three ways 
' See documentation topic: Using Addresses 
Function Util_UsingAddresses() 
Dim objNewMessage As Message   ' new message to add recipients to 
Dim objNewRecips As Recipients ' recipients of new message 
Dim strAddrEntryID As String   ' ID value from AddressEntry object 
Dim strName As String          ' Name from AddressEntry object 
 
On Error GoTo error_olemsg 
If objOneMsg Is Nothing Then 
    MsgBox "Must select a message" 
    Exit Function 
End If 
With objOneMsg.Recipients.Item(1).AddressEntry 
    strAddrEntryID = .ID 
    strName = .Name 
End With 
Set objNewMessage = objSession.Outbox.Messages.Add 
If objNewMessage Is Nothing Then 
    MsgBox "Unable to add a new message" 
    Exit Function 
End If 
Set objNewRecips = objNewMessage.Recipients 
 
' Add three recipients 
' 1. look up entry in address book specified by profile 
Set objOneRecip = objNewRecips.Add( _ 
                               Name:=strName, _ 
                               Type:=CdoTo) 
If objOneRecip Is Nothing Then 
    MsgBox "Unable to add recipient using display name" 
    Exit Function 
End If 
objOneRecip.Resolve ' this looks up the entry 
 
' 2. add a custom recipient 
Set objOneRecip = objNewRecips.Add( _ 
                               Address:="SMTP:someone@microsoft.com", _ 
                               Type:=CdoTo) 
If objOneRecip Is Nothing Then 
    MsgBox "Unable to add recipient using custom addressing" 
    Exit Function 
End If 
objOneRecip.Resolve ' assign entry identifier 
 
' 3. add an existing valid address entry object 
Set objOneRecip = objNewRecips.Add( _ 
                               entryID:=strAddrEntryID, _ 
                               Type:=CdoTo) 
If objOneRecip Is Nothing Then 
    MsgBox "Unable to add recipient using existing address entry" 
    Exit Function 
End If 
 
objNewMessage.Text = "Expect 3 different recipients" 
MsgBox ("Count = " & objNewRecips.Count) 
' you can also call resolve for the whole collection 
' objNewRecips.Resolve (True) ' resolve all; show dialog 
 
objNewMessage.Subject = "Addressing test" 
objNewMessage.Update ' commit the message to storage in MAPI system 
objNewMessage.Send showDialog:=False 
Exit Function 
 
error_olemsg: 
MsgBox "Error " & Str(Err) & ": " & Error$(Err) 
Exit Function 
 
End Function

Using Addresses

See Also