IMessenger::SendMail Method

  • Article

Deprecated. Launches a new message in the client's default e-mail application with the To: line prepopulated with the sign-in name of the specified contact.

Syntax

HRESULT SendMail(      
    VARIANT vContact
);

Parameters

  • vContact
    [in] A VARIANT that can take as its value either a VT_BSTR string or a VT_DISPATCH pointer to an existing MessengerContact object. If the input value type is a string, this method creates a new MessengerContact object internally. The string should be the full sign-in name. For a Microsoft .NET Messenger Service contact, this should include the "@" symbol and domain name. If the input value type is a pointer to an existing MessengerContact object (should be type VT_DISPATCH), the existing object is used.

Return Value

For a table of MSGR_E_* constants, see MSGRConstants.

Returns one of the following values:

S_OK Success.
E_INVALIDARG

vContact value is NULL, the wrong type, points to a NULL string, or points to a string that has a space as the first character.

- or -

vContact is a VT_BSTR that exceeded 129 characters (130 if the string terminator is included in the cout. This allows for a 64-character sign-in name, @ symbol, and a 64-character domain name. This format does not have to be followed.)

- or -

vContact is a VT_BSTR and contains a carriage return or linefeed.
MSGR_E_NOT_LOGGED_ON The client is not logged in.

Remarks

When this method is invoked on a Microsoft Exchange Instant Messaging Service (IM) client, Exchange through Microsoft Outlook will always be invoked as the mail client. Calling this method will launch or focus the 32-bit Outlook application with a new message to the specified contact.

At sign-in, the Messenger client internally flags whether the .NET Messenger Service user has a MSN Hotmail Inbox. If so, a browser instance will be opened to the Hotmail compose page, prefilled with the e-mail or sign-in name of the desired contact. If the user does not have a Hotmail Inbox, then a default mailto: is thrown to the operating system, which opens the mail client registered to handle this protocol in the Microsoft Internet Explorer browser. In this case, most clients will allow the target e-mail name to be passed as part of a mailto: call and the To: line to be prefilled per the vContact parameter. This behavior is identical to the Send Mail menu option in the client user interface (UI).

In addition to dependencies on the service used by the local client user, there are also issues with the service of the contact to whom the mail is sent (for example, if vContact is a MessengerContact object in a service other than .NET Messenger Service and Exchange IM). Not all services will always have an e-mail address accessible. Services might produce MessengerContact objects where there is no available e-mail address or no Messenger implementation for storing the e-mail address as a separate property from the sign-in name.

To use this method with Microsoft Windows Messenger, you must install an add-in component that supports e-mail integration.

This method does not generate a conversation window, even though it takes a VARIANT form parameter for vContact like similar methods that do.

For Hotmail, this method will always open a new default browser instance. This method cannot detect if other browser instances had a compose window or other functional areas of Hotmail open. If Windows Live ID authentication is required to open the Hotmail compose window, the authentication will take place automatically.

Users of @hotmail.com always have an e-mail account associated with the sign-in name used for Messenger. Users of @passport.com may authenticate through Windows Live ID into .NET Messenger Service, but these users do not have corresponding e-mail accounts with either passport.com or hotmail.com as providers. Because Windows Live ID supports e-mail name as sign-in name (EASI), a user can sign in through Windows Live ID to the .NET Messenger Service with a sign-in name that does not have either the @passport.com or @hotmail.com suffix. In those cases in which there is no Hotmail Inbox for the local client user, IMessenger::SendMail will launch the default mail client.

Note  This method is available for scripting languages.

Important  IMessenger::SendMail is no longer available in Windows Vista. See Windows Messenger for more information.