Using Addresses

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 “john@example.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:

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 can also optionally 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:user@example.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
 

See Also

Changing an Existing Address Entry

See Also

Concepts

Programming Tasks