3.77 Recipients

A collection of Recipient objects.

3.77.1 Properties

The following table lists properties along with their access and descriptions.

Property

Access

Description

Application

R/O

Application. The Application object.

Count

R/O

Long. The number of objects in this collection.

_NewEnum

R/O

Enumeration object. Implements IEnumVARIANT. For Windows only.

Parent

R/O

Message. The Message object that owns this collection.

3.77.2 Methods

Recipient Add(Address Address, [AddressTargetTypeConstants TargetType])

Creates an unresolved Recipient object from an Address object, then adds the Recipient object to the collection. The new Recipient’s Address property is set to the Address object given, and its DisplayName, EmailAddress, and EmailType are copied from the Address object. If TargetType is omitted, egwTo is assumed. Returns the new Recipient. See Remarks below.

Recipient Add(Addresses Addresses, [AddressTargetTypeConstants TargetType])

Creates unresolved Recipients for each Address in the Addresses collection given, and adds each Recipient object to the collection. If TargetType is omitted, egwTo is assumed. Returns nothing. See Remarks below.

Recipient Add(String EmailAddress, [String EmailType], [AddressTargetTypeConstants TargetType])

Creates an unresolved Recipient from the EmailAddress, EmailType, and TargetType, then adds the Recipient object to the collection. If EmailType is omitted, an empty string ("") is assumed. If TargetType is omitted, egwTo is assumed. The new Recipient’s Address property is set to Nothing and its DisplayName is set to EmailAddress. Returns the new Recipient. See Remarks below. See also AddressTargetTypeConstants.

Recipient AddByDisplayName(String DisplayName, [AddressTargetTypeConstants TargetType])

Creates an unresolved Recipient from DisplayName, then adds it to the collection. If DisplayName is an empty string (""), an exception is thrown. If TargetType is omitted, To is assumed. The new Recipient Address property is set to Nothing and its EmailAddress and EmailType are set to an empty string (""). Returns the new Recipient. See AddressTargetTypeConstants.

Recipient Item(Long Index)

DEFAULT. Returns the Recipient object located at the given Index in the collection. Valid indexes are 1 through Count inclusive. Throws an exception if the Index is outside of this range.

Resolve([AddressBook ResolveTo])

Performs a Resolve on each Recipient in the collection. If an error occurs, it leaves that recipient unresolved and proceeds to the next recipient. Throws an exception if any recipients failed to resolve. Check the Resolved property of each Recipient object to determine which ones failed.

3.77.3 Remarks

The Add method template is as follows:

Add(VARIANT P1, [VARIANT P2], [VARIANT P3])

The Add method checks the P1 type at runtime.

  • If P1 is an Address object, the first form of Add is assumed; P2, if present, must be a TargetType Enum of type AddressTargetTypeConstants, and P3 must not be present.

  • If P1 is an Addresses collection, the second form of Add is assumed; P2, if present, must be a TargetType Enum of type AddressTargetTypeConstants, and P3 must not be present.

  • If P1 is a String, the third form of Add is assumed; P2, if present, must be a string, and P3, if present, must be a Target Enum of type AddressTargetTypeConstants.

For example, you can use either of the following examples to Add a recipient:

Mail.Recipients.Add('devsup@novell.com', 'NGW', egwTo);
Mail.Recipients.Add('devsup@novell.com', 'NGW');

AddByDisplayName must be a separate method from Add, since EmailAddress and DisplayName are both Strings and cannot be distinguished by type.

A Recipients collection is refreshed when its parent object is refreshed. When a Recipients collection is refreshed, it recursively refreshes its contained Recipient objects.