BOOL ComposeMessage(
	LPCTSTR lpszFrom,
	LPCTSTR lpszTo,
	LPCTSTR lpszCc,
	LPCTSTR lpszSubject,
	LPCTSTR lpszMessageText,
	LPCTSTR lpszMessageHTML,
	UINT nCharacterSet,
	UINT nEncodingType
);

The ComposeMessage method creates a new message using the specified parameters.

Parameters

lpszFrom

A pointer to a string which specifies the sender's email address. This parameter may be NULL, in which case no sender address will be included in the message header.

lpszTo

A pointer to a string which specifies one or more recipient addresses. If multiple addresses are specified, each address must be separated by a comma. This parameter may be NULL, in which case no recipient addresses will be included in the message header.

lpszCc

A pointer to a string which specifies one or more addresses that will receive a copy of the message in addition to the listed recipients. If multiple addresses are specified, each address must be separated by a comma. This parameter may be NULL, in which case no carbon-copy addresses will be included in the message header.

lpszSubject

A pointer to a string which specifies the subject of the message. This parameter may be NULL, in which case no subject will be included in the message.

lpszMessageText

A pointer to a string which contains the body of the message as plain text. Each line of text contained in the string should be terminated with a carriage-return and linefeed (CRLF) pair, which is recognized as the end-of-line. If this parameter is NULL or points to an empty string, then the message will have an empty body unless the lpszMessageHTML parameter is not NULL.

lpszMessageHTML

A pointer to a string which contains the message using HTML formatting. If the lpszMessageText parameter is not NULL, then a multipart message will be created with both plain text and HTML text as the alternative. This allows mail clients to select which message body they wish to display. If the lpszMessageText argument is NULL or points to an empty string, then the message will only contain HTML. Although this is supported, it is not recommended because older mail clients may be unable to display the message correctly.

nCharacterSet

A numeric identifier which specifies the character set to use when composing the message. A value of zero specifies that the default UTF-8 character set should be used. It is recommended that you always use UTF-8 when composing a new message or creating a new message part.

nEncodingType

A numeric identifier which specifies the encoding type to use when composing the message. A value of zero specifies that default 7bit encoding should be used. The following values may also be used:

Constant	Description
MIME_ENCODING_7BIT	Each character is encoded in one or more bytes, with each byte being 8 bits long, with the most significant bit cleared. This encoding is most commonly used with plain text using the US-ASCII character set, where each character is represented by a single byte in the range of 20h to 7Eh.
MIME_ENCODING_8BIT	Each character is encoded in one or more bytes, with each byte being 8 bits long and all bits are used. 8-bit encoding is typically used with multibyte character sets and is the default encoding used with Unicode text.
MIME_ENCODING_QUOTED	Quoted-printable encoding is designed for textual messages where most of the characters are represented by the ASCII character set and is generally human-readable. Non-printable characters or 8-bit characters with the high bit set are encoded as hexadecimal values and represented as 7-bit text. Quoted-printable encoding is typically used for messages which use character sets such as ISO-8859-1, as well as those which use HTML.
MIME_ENCODING_BASE64	Base64 encoding converts binary or text data to ASCII by translating it so each base64 digit represents 6 bits of data. This encoding method is commonly used with messages that contain binary data (such as binary file attachments), or when text uses extended characters that cannot be represented by 7-bit ASCII. It is recommended that you use base64 encoding with Unicode text.

Return Value

If the method succeeds, the return value is non-zero. If the method fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

email addresses may be specified as simple addresses, or as commented addresses that include the sender's name or other information. For example, any one of these address formats are acceptable:

user@domain.tld
User Name <user@domain.tld>
user@domain.tld (User Name)

To specify multiple addresses, you should separate each address by a comma or semi-colon. Note that the lpszFrom parameter cannot specify multiple addresses, however it is permitted with the lpszTo, lpszCc and lpszBcc parameters.

To send a message that contains HTML, it is recommended that you provide both a plain text version of the message body and an HTML formatted version. While it is permitted to send a message that only contains HTML, some older mail clients may not be capable of displaying the message correctly. In some cases, anti-spam software will increase the spam score of messages that do not contain a plain text message body. This can result in your message being rejected or quarantined by the mail server.

Requirements

Minimum Desktop Platform: Windows 7 (Service Pack 1)
Minimum Server Platform: Windows Server 2008 R2 (Service Pack 1)
Header File: cstools10.h
Import Library: csmsgv10.lib
Unicode: Implemented as Unicode and ANSI versions.

See Also

CreatePart, ExportMessage, ImportMessage

Copyright © 2023 Catalyst Development Corporation. All rights reserved.