The Post Office Protocol (POP3) and Internet Message Access Protocol (IMAP4) are the application protocols used to retrieve and manage e-mail messages that are stored on a mail server. The Simple Mail Transfer Protocol (SMTP) is used to submit a message to a mail server for delivery. These protocols, along with the Multipurpose Internet Message Extensions (MIME) standard form the core of the Internet e-mail system.
The Internet Mail .NET interface is designed to be simple and intuitive, yet flexible enough to handle a wide variety of development needs. You can connect to the mail server to download messages to the local system, or use the class to scan the message headers for specific content. If you are connected to an IMAP4 server, there's also a number of additional features that are available which allow you to search and manage messages stored there. The InternetMail class provides common methods that makes it easy to support both protocols in your application.
Initialize
Initialize an instance of the class, loading the networking library
and 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.
Connect
Connect to the mail server using either a host name or IP address.
The method has several options related to security as well as the
general operation of the class. This method is used when
establishing a connection to download or manage the e-mail messages
on a mail server. Note that it is not required to call the
Connect method when sending an e-mail message.
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.
Disconnect
Disconnect from the server and release the memory allocated for
that client session. After this method is called, the client
session is no longer valid. This method should always be called
once the connection established with the Connect
method is no longer needed. Each call to the
Connect method should be matched with a call to
the Disconnect method.
Reset
Reset the internal state of the component. This can be useful if
your application wishes to discard any settings made by a user and
return that instance of the class to its default state. This will
also destroy the contents of the current message that was retrieved
using the GetMessage method, or created using the
ComposeMessage method.
Uninitialize
Unload the networking library and release any resources that have
been allocated for the current process. This is the last method
call that the application should make prior to terminating. Each
call to the Initialize method should be matched
with a call to the Uninitialize method.
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 is to 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.
MessageText
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.
MessagePart
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.
MessageParts
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 ClearMessage
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.
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@bigcorp.com>"; this method would parse the address
and return "joe@bigcorp.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@bigcorp.com>, Jerry
Lewis <jerry@bigcorp.com>"; this property array would return
"tom@bigcorp.com" and "jerry@bigcorp.com" as the two addresses
listed. The total number of addresses that are available is
returned by the Recipients property.
There are methods in the InternetMail class for retrieving and managing messages on the mail server. Messages are identified by a number, starting with one for the first message in the mailbox. The most typical operation for an application is to retrieve each message, store it on the local system and then delete the message from the server. Any processing that is done on the message would then be done on the local copy.
MessageIndex
This property sets or returns the message number for the currently
selected mailbox. Message numbers range from 1 through the number
of messages available on the server, as returned by the
MessageCount property.
MessageCount,
LastMessage
A property which returns the number of messages available for
retrieval. There are two values the application should use. One is
the number of currently available messages and the other is the
last valid message number. As messages are deleted from the server,
the total number of available messages will decrease; however, the
last available message number will remain constant.
MessageSize
This property returns the size of the message in bytes. One thing
to be aware of when using this method is that some servers will
only return approximate message sizes. In addition, because of the
difference between the end-of-line characters on UNIX and Windows
systems, the size reported by the server may not be the actual size
of the message when stored on the local system. Therefore, the
application should not depend on this value as an absolute. For
example, it should not use this value to determine the maximum
number of bytes to read from the server; instead, it should read
until the server indicates that the end of the message has been
reached.
GetHeaders
This method retrieves the complete headers for the specified
message and stores it in a string or byte array provided by the
caller. This method can also be used to overwrite the current
message contents, replacing it with the header values returned by
the server.
GetMessage
This method is used to retrieve a message from the server and copy
it into a local string or byte array buffer. This method can also
be used to overwrite the current message contents with the message
retrieved from the server. The current thread will block until the
message transfer completes, a timeout occurs or the transfer is
canceled.
StoreMessage
This method downloads a complete message and stores it as a text
file on the local system. This is useful for applications that want
to store a local copy of the message and then remove it from the
mailbox on the server.
DeleteMessage
Mark the message for deletion. When the connection with the server
is closed, the message will be removed from the user's inbox. An
important difference between the POP3 and IMAP protocols is that
when a message is marked as deleted on a POP3 server, that message
can no longer be accessed. An attempt to retrieve a message after
it has been marked for deletion will result in an error. The only
way to undelete a message once it has been deleted is to terminate
the connection with the server by calling the Reset method instead
of calling the Disconnect method.
One of the primary differences between the IMAP and POP3 protocol is that IMAP is designed to manage messages on the mail server, rather than downloading all of the messages and storing them on the local system. To support this, IMAP allows the client to maintain multiple mailboxes on the server, which are similar in concept to message folders used by mail client software. A mailbox can contain messages, and in some cases a mailbox can contain other mailboxes, forming a hierarchy of mailboxes and messages, similar to directories and files in a file system. A special mailbox named INBOX contains new messages for the user, and additional mailboxes can be created, renamed and deleted as needed. The following are the most important methods for managing mailboxes:
CheckMailbox
Check the mailbox for any new messages which may have arrived.
Because messages are managed on the server, it is possible for new
mail to arrive during the client session.
CreateMailbox
Create a new mailbox on the server with the specified name.
DeleteMailbox
Delete a mailbox from the server. Most servers will only permit a
mailbox to be deleted if it does not contain any mailboxes itself.
Unlike deleting a message, which can be undeleted, deleting a
mailbox is permanent.
RenameMailbox
Renames an existing mailbox. One of the interesting uses of this
method is the ability to rename the special INBOX mailbox. Instead
of actually renaming it, it moves all of the messages to the new
mailbox and empties the INBOX.
SelectMailbox
Once the session has been established and authenticated, a mailbox
should be selected. Selecting a mailbox enables the client to
manage the messages in that mailbox. This method selects the
specified mailbox in read-write mode so that changes can be made to
the mailbox.
UnselectMailbox
This method unselects the currently selected mailbox, and allows
the caller to specify if messages marked for deletion should be
expunged (removed) from the mailbox or reset back to an undeleted
state.
Sending an e-mail message is a simple process and typically involves calling a single method. There are also additional properties which allow you to specify the name of a relay server which will handle the routing and delivery of the message.
RelayServer
This property is used to specify the host name or IP address of the
mail server which will accept the message and handle the process
delivering the message to the recipients. If this property is not
set, then the class will attempt to deliver the message to the
recipient by connecting directly to the mail server that is
responsible for accepting e-mail in their domain. If you are
connected to the Internet using a dial-up networking connection,
you will typically need to set this property to the host name of
your service provider's mail server.
RelayPort
This property is used to specify the port number that the
application should use when establishing a connection with the mail
server. By default, the standard port for the Simple Mail Transfer
Protocol will be used. This property value only has meaning if the
RelayServer property has also been set.
SendMessage
This method is used to submit the current message, typically
created using the ComposeMessage method, to a mail
server for delivery. If a relay server has not been specified then
the method will attempt to connect directly to the mail server
responsible for accepting messages for the recipient. Two events
are generated during the process of submitting the message for
delivery. Before the message is submitted to the mail server, the
OnRecipient
event will fire. After the message has been submitted, the OnDelivered event
will fire, specifying the recipient address. If an error occurs
during the delivery process, the OnError event will
fire.