The Internet Message Access Protocol (IMAP) is an application protocol which is used to access a user’s e-mail messages which are stored on a mail server. However, unlike the Post Office Protocol (POP) where messages are downloaded and processed on the local system, the messages on an IMAP server are retained on the server and processed remotely. This is ideal for users who need access to a centralized store of messages or have limited bandwidth. The SocketTools IMAP class implements the current standard for this protocol, and provides methods to retrieve messages, create and manage mailboxes, and search for specific messages based on some user-defined search criteria.
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
Establish a connection to the IMAP server. Once the connection has
been established, the other methods in the class may be used to
access the messages on the server.
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.
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.
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. This is
only necessary if the application has previously called the
Initialize 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 filesystem. 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.
ExamineMailbox
Once the session has been established and authenticated, a mailbox
should be selected. This enables the client to manage the messages
in that mailbox. This method selects the specified mailbox in
read-only mode so that messages can be read, but not modified. To
select the mailbox in read-write mode, use the SelectMailbox
method.
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.
There are methods in the IMAP class for managing messages which enables the application to create, delete and move messages. To use these methods, a mailbox must be selected, either by setting the MailboxName property or calling the SelectMailbox method. Methods which modify the mailbox require that it be opened in read-write mode. Messages are identified by a number, starting with one for the first message in the mailbox.
CopyMessage
Copy a message to a specific mailbox.
DeleteMessage
Mark the specified message for deletion. Unlike the POP3 protocol,
when a message is deleted on an IMAP server it can still be
accessed. The message will not actually be removed from the mailbox
unless the mailbox is expunged, unselected or the client
disconnects from the server.
UndeleteMessage
Remove the deletion flag from the specified message.
One of the more powerful features of the IMAP protocol is the ability to precisely select what kinds of message data you wish to retrieve from the server. It is possible to retrieve only specific headers, or specific sections of a multipart message. Because IMAP understands MIME formatted messages, it is possible to only retrieve the textual portion of a message without having to download any attachments that may have come with it.
GetHeader
This method returns the value for a specified header field in the
message. Using this method, it is not necessary to download and
parse the message header.
GetHeaders
This method retrieves the complete headers for the specified
message and stores it in a string or byte array provided by the
caller.
GetMessage
The GetMessage method retrieves the specified message and stores it
in a string or byte array provided by the caller; you can specify
the type of message data that you want, a specific part of a
multipart message and the amount of data that you want. For
example, it is possible to request that only the first 1500 bytes
of the body of the 3rd part of a multipart message should be
returned.
OpenMessage
The OpenMessage method is a lower level method which opens a
message for reading from the server. The application would then
call Read to read the contents of the message, followed by
CloseMessage when all the message data has been read. Also see the
GetMessage method, which will return the contents of a message into
a string or byte array.
In some cases, it may be preferable to download a complete message from the server to the local system. This can be easily done with a single method call.
StoreMessage
This method downloads a complete message and stores it as a text
file on the local system.