The class can also be used to create new multipart messages with alternative content, such a message with both plain text and styled HTML text. Once a message has been created, files can be attached to the message and the application can make any other changes that are needed. The class provides complete access to all headers and content in a multipart message, including the ability to create your own custom headers and make modifications to specific sections.
Initialize
Initialize an instance of the class, validating the development license.
This method must be called before any properties are changed or any
other methods in this class are called by the application.
ComposeMessage
Compose a new message using the specified header field values and
content. Using this method, you can create a message with the From, To,
Cc and Subject headers already defined, along with any text for the
message. You can also optionally provide both plain and styled HTML text
versions of the message and the method will automatically create a
multipart message.
ClearMessage
Releases the memory allocated for the current message, including any
file attachments, and creates a new, empty message.
Uninitialize
Release any resources that have been allocated for the class instance.
This method is automatically invoked when the class instance is disposed
or goes out of scope.
Each message has one or more headers fields which provide information about the contents of the message. For example, the "From" header field specifies the email address of the person who sent the message. There are a fairly large number of header fields defined by the MIME standard, and applications can also create their own custom headers if they wish. The class gives the application complete access to the header fields in a message. Headers can be examined, modified, created or removed from the message as needed.
GetHeader
This method copies the value of a header field into a string buffer that
you provide. To return the value of the common header fields such as
"From", "To" and "Subject", you should specify a message part of zero by
setting the MessagePart property.
GetFirstHeader
This method returns the value of the first header defined in the current
message part, copying it into the string buffer that you provide. This
is used in conjunction with the GetNextHeader method to enumerate all of
the headers that have been defined.
GetNextHeader
This method returns the value of the next header defined in the current
message part. It should be called in a loop until it returns a value of
zero (False) which indicates that the last message header has been
returned.
SetHeader
Set a message header field to the specified value in the current message
part. If the value is an empty string, the message header will be
deleted from the message.
DeleteHeader
Delete the specified message header from the current message part.
The content or body of a message contains the text that will be read or processed by the recipient. It may be a simple, plain text message or it may be more complex, such as a combination of plain and styled HTML text or the data for a file attachment. The class provides complete access to the contents of the message, enabling the application to modify, extract, replace or delete specific sections of the message.
Message
This property returns the current message, including the headers and all
message parts, as a string. Setting this property will cause the current
message to be cleared and replaced by the new value. The string contents
must follow the standard specifications for a message. If the property
is set to an empty string, the current message is cleared.
Text
This property returns the body of the current message part. Setting this
property replaces the entire message body with the new text.
Most typical messages contain a single part, which consists of the message headers followed by the contents of the message. However, when files are attached to a message or alternative content types such as HTML are used, a more complex multipart message is required. With a multipart message, the contents of the message are split into logical sections with each section containing a specific part of the message. For example, when a file is attached to a message, one part of the message contains the text to be read by the recipient and another part contains the data for the file.
The first of a multipart message is called part 0, and contains the main header block. This is what defines the headers that you are most familiar with, such as "From", "To" and "Subject". The body of this message part is typically a plain text message that indicates that this is a multipart message. This is done for the benefit of older mail clients that cannot parse MIME messages correctly. Next part, part 1, typically contains the actual body of the message that would be displayed by the mail client. Additional parts may contain file attachments and other information. In the case of a multipart message that contains both plain and styled HTML text versions of a message, part 1 is typically the plain text version of the message while part 2 contains the HTML version. The mail client can then make a decision based on its own configuration as to which version of the message it displays.
Part
This property returns the current message part index. All messages have
at least one part, which consists of one or more header fields, followed
by the body of the message. The default part, part 0, refers to the main
message header and body. If the message contains multiple parts (as with
a message that contains one or more attached files), this property can
be set to refer to that specific part of the message.
PartCount
This property returns the number of parts in the current message. All
messages have at least one part, referenced as part 0. Multipart
messages will consist of additional parts which may be accessed by
setting the Part property.
CreatePart
Create a new, empty message part. If the message was not originally a
multipart message, it will be restructured into one. Otherwise, the new
part is simply added to the end of the message. This method will cause
the current message part to change to the new part that was just
created.
DeletePart
Delete the message part from the message. If the message part is in the
middle of the message, it will cause the subsequent parts of the message
to be reordered. You should not delete part zero to delete a message;
use the DeleteMessage method instead.
The class can be used to import existing messages from a text file and export messages to a text file. Once the message has been parsed, the application can examine or modify specific parts of the message. The following methods are provided to import and export the contents of a message:
ImportMessage
The simplest method of importing a message, this method reads the
contents of the specified file and imports it into the current message.
Note that the current message contents will be overwritten with the
imported message.
ExportMessage
This method exports the current message to a file. When using this
method, only certain headers are exported and they may be reordered. To
force all headers to be included in the message or to preserve the order
of the headers, set the Options property.
In addition to simple text messages, one or more files can be attached to a message. The process of attaching a file involves creating a multipart message, encoding the contents of the file and then including that encoded data in the message. The following methods are provided to manage files attached to the message, as well as attach files to an existing message:
Attachment
A property which returns the name of a file attachment in the current
message part. This property serves two purposes, to determine if the
current message part contains a file attachment, and if so, what file
name should be used when extracting that attachment.
AttachFile
This method attaches the contents of the file to the message. The file
will be attached using the specified encoding algorithm and will become
the current message part. If the message is not a multipart message, it
will be converted to one; if it already is a multipart message, the
attachment will be added to the end of the message.
AttachData
This method works in similar fashion to AttachFile, except that instead
of the contents of a file, the data in a memory buffer will be attached
to the message. If the message is not a multipart message, it will be
converted to one; if it already is a multipart message, the attachment
will be added to the end of the message.
AttachImage
This method attaches an inline image file to the message. It is similar
to the AttachFile method, except that the image is designed to be
referenced as an embedded graphic in an HTML message. This method will
automatically set the correct header values for an inline image
attachment, and enables the developer to specify a content ID which is
used in the HTML message.
ExtractFile
Extract the file attachment in the current message part, storing the
contents in a file. The attachment will automatically be decoded if
necessary. This method also recognizes uuencoded attachments that are
embedded directly in the body of the message, rather than using the
standard MIME format.
The Mail Message class also has methods which are designed to make it easier to work with email addresses. Addresses are typically in the format of "user@domain.com" however additional information can be included with the address, such as the user's name or other comments that aren't part of the address itself. The class can parse these addresses for you, returning them in a format that is suitable for use with other protocols such as the SMTP class.
ParseAddress
Parse an email address that may include an address without a domain name
or comments in the address, such as the user's name. For example, the
From header field may return an address like "Joe Smith <joe@example.com>";
this method would parse the address and return "joe@example.com", the
actual address for the user.
Recipient
It is common for certain headers to contain multiple addresses separated
by a comma. These addresses may also include comments such as the user's
name. This property array returns a list of valid addresses defined in
the current message. For example, the To header field may contain "Tom
Jones <tom@example.com>, Jerry Lewis <jerry@example.com>"; this property
array would return "tom@example.com" and "jerry@example.com" as the two
addresses listed. The total number of addresses that are available is
returned by the Recipients property.
The Mail Message class has a collection of methods which makes it simple for an application to store a group of messages together in a single file, search for and retrieve specific message. The collection of messages is referred to as a "message store" and messages may either be stored in a plaintext format or in a compressed binary format.
OpenStore
This method is used to open an existing message store or creates a new storage
file. If a storage file has been opened previously, it will be closed and the
new storage file will be opened. The storage
files may either be plaintext, or stored in a compressed format. It also
supports opening storage files in the UNIX mbox format.
StoreSize
This property returns the total number of messages that currently in the message
store, including deleted messages. Each message is referred to by an integer
which is its index into the storage file.
StoreIndex
This property specifies the current message index into the storage file.
Messages are identified by an integer value that starts at one for the first
message and increments for each additional message in the storage file. If no
message store has been opened, this property will return a value of zero.
Changing the value of this property changes the current message index for the
message store.
FindMessage
An application can search the message store for messages that match any header
value. Searches can be complete or partial, and may be case-sensitive or
case-insensitive. For example, this method can be used to enumerate all of the
messages in the storage file that were sent by a specific user or match a
specific subject.
ReadStore
This method reads a message from the storage file and replaces the current
message. If the application modifies the message, it can replace the message in
the storage file or discard the changes.
WriteStore
This method writes the current message to the message store. Note that the
message store must be opened for write access, and the message will always be
appended to the storage file. The StoreIndex property is updated with the index
value for the new message.
DeleteMessage
This method flags a message for deletion from the message store. Once a message
has been flagged for deletion, it may no longer be accessed by the application.
When the storage file is closed, the contents of the deleted message will be
removed from the file.
ReplaceMessage
This method replaces an existing message in the storage file, overwriting it
with the current message. Unlike many of the other methods which do not
permit the application to reference a deleted message, this method can be used
to replace a previously deleted message.
CloseStore
The message store must be closed when the application has finished accessing it.
This method updates the storage file with any changes, purges all deleted
messages and closes the storage file. If the storage file is locked for
exclusive access, this method will release that lock, allowing another process
to open the file