mailResolveRecipient

Description

Obtains a valid e-mail address based on a partial or full user name and optionally updates information in the system’s address list if the user has privileges to do so.

Applies to

mailSession object

Syntax

mailsession.mailResolveRecipient ( recipient {, allowupdates } )

Argument

Description

mailsession

A mailSession object identifying the session in which you want to resolve the recipient.

recipient

A mailRecipient structure or a string variable whose value is a recipient’s name. The recipient’s name is a property of the mailRecipient structure. MailResolveRecipient sets the value of the string to the recipient’s full name or the structure to the resolved address information.

allowupdates (optional)

A boolean indicating whether updates to the recipient’s name will be allowed. If the user does not have update privileges for the mail system, then allowupdates is ignored. The default is false.

Returns

mailReturnCode. Returns one of the following values:

If any argument’s value is null, mailResolveRecipient returns null.

Usage

Use mailResolveRecipient to verify that a name is a valid address in the mail system. The function reports mailReturnFailure! if the name is not found.

If you supply a mailRecipient structure, mailResolveRecipient fills the structure with valid address information when it resolves the address. If you supply a name as a string, mailResolveRecipient replaces the string’s value with the full user name as recognized by the mail system. An address specified as a string is adequate for users in the local mail system. If you are sending mail through gateways to other systems, you should obtain full address details in a mailRecipient structure.

If more than one address on the mail system matches the partial address information you supply to mailResolveRecipient, the mail system may display a dialog box allowing the user to choose the desired name.

If you supply a mailRecipient structure that already has address information, mailResolveRecipient corrects the information if it differs from the mail system. If you set allowupdates to true and the information differs from the mail system, mailResolveRecipient corrects the mail system’s information if the user has rights to do so. Be careful that the address information you have is correct when you allow updating.

Before calling mail functions, you must declare and create a mailSession object and call mailLogon to establish a mail session.

Examples

Example 1

This example checks whether there is a user J Smith is on the mail system. If there is a user whose name matches, such as Jane Smith or Jerry Smith, the variable mname is set to the full name. If both names are on the system, the mail system displays a dialog box from which the user chooses a name. Mname is set to the user’s choice. The application has already created the mailSession object mSes and logged on:

mailReturnCode mRet

string mname

mname = "Smith, J"

mRet = mSes.mailResolveRecipient(mname)

IF mRet = mailReturnSuccess! THEN

    MessageBox("Address", mname + " found.")

ELSEIF mRet = mailReturnFailure! THEN

    MessageBox("Address", "J Smith not found.")

ELSE

    MessageBox("Address", "Request not evaluated.")

END IF

Example 2

In this example, sle_to contains the full or partial name of a mail recipient. This example assigns the name to a mailRecipient object and calls mailResolveRecipient to find the name and get address details. If the name is found, mailRecipientDetails displays the information and the full name is assigned to sle_to. The application has already created the mailSession object mSes and logged on:

mailReturnCode mRet

mailRecipient mRecip


mRecip.Name = sle_to.Text

mRet = mSes.mailResolveRecipient(mRecip)

IF mRet <> mailReturnSuccess! THEN

    MessageBox ("Address", &

      sle_to.Text + "not found.")

ELSE

    mRet = mSes.mailRecipientDetails(mRecipient)

    sle_to.Text = mRecipient.Name

END IF

See also