In addition to composing and sending e-mail messages, the Internet Mail control has the ability to retrieve a specific user's messages from a mail server. There are a number of properties which are used to access and manage a user's mailbox:

The ServerName, ServerPort, UserName and Password properties are used in establishing a connection with the mail server and authenticating the specified user. The Timeout property determines the amount of time the control spends waiting for an operation to complete before returning an error. The remaining properties are used to manage the mailbox or return information about the mailbox, such as the number of messages that are available to be retrieved.

There are also several methods available which can be used to access the user's mailbox:

The Connect method establishes a connection with the mail server and has a number of optional arguments. In its simplest form, a connection can be established like this:

InternetMail1.ServerName = strMailServer
InternetMail1.UserName = strUserName
InternetMail1.Password = strPassword

nError = InternetMail1.Connect()
If nError <> 0 Then
    MsgBox "Unable to connect to mail server" & vbCrLf & _
           InternetMail1.LastErrorString, vbExclamation
    Exit Sub
End If

nMessages = InternetMail1.MessageCount
InternetMail1.Disconnect

MsgBox "There are " & nMessages & " messages " & _
       "in this mailbox", vbInformation

Once a connection has been established, the MessageCount property will return the number of messages that are currently available and the LastMessage property will return the total number of messages that were available when the session began. This is an important distinction because as messages are deleted from the mailbox, the MessageCount value will decrease while the LastMessage value remains unchanged for the current session.

The MessageIndex property is used to select the current message in the mailbox. Once a message has been selected, the header for the message is retrieved, but not the entire contents. This allows an application to use the various header-related properties and methods without incurring the overhead of downloading the complete message. For example, the following code would add the subject of each message in the mailbox to a list control:

For nMessage = 1 To InternetMail1.LastMessage
    InternetMail1.MessageIndex = nMessage
    List1.AddItem InternetMail1.Subject
Next

The GetMessage method is used to retrieve a complete message including the headers, body and any attachments. As the message is being downloaded, the OnProgress event will fire, notifying the application of how much of the message has been retrieved. Once the complete message has been downloaded, the GetMessage method will return and the program can continue processing the message. The following code retrieves all of the messages from a mailbox, and then scans each message to determine if it contains any file attachments:

For nMessage = 1 To InternetMail1.LastMessage

    ' Retrieve the message

    InternetMail1.GetMessage nMessage

    ' For each part of the message, check the value of the
    ' Attachment property; if it has a value, then this is
    ' the name of a file attachment in the current message part

    For nPart = 0 To InternetMail1.MessageParts - 1
        InternetMail1.MessagePart = nPart
        strFileName = InternetMail1.Attachment
        If Len(strFileName) > 0 Then

            ' This message part is an attachment, it could be
            ' extracted, the name added to a listbox, etc.

        End If
    Next
Next

The StoreMessage method is similar to GetMessage in that it retrieves a message from the server, but instead of loading the message into the control, it stores the message as a text file. This will not change the current message, nor will it cause the message to be processed in any way by the control; the data is stored in the file exactly as it is downloaded from the server. This can be useful if the application wants to store messages locally for processing later. The following example demonstrates how StoreMessage can be used:

For nMessage = 1 To InternetMail1.LastMessage
    strFileName = "c:\temp\msg" & Format(nMessage, "00000") & ".txt"
    nError = InternetMail1.StoreMessage(nMessage, strFileName)
    If nError <> 0 Then
        MsgBox "Unable to store message " & nMessage & vbCrLf & _
               InternetMail1.LastErrorString, vbExclamation
        Exit For
    End If
Next

Once a message has been retrieved, either for processing or storage, the application may wish to remove the message from the mailbox by calling the DeleteMessage method. This method marks the specified message for deletion, and when the session is closed (by calling the Disconnect method), the message is permanently deleted from the mailbox. Once a message has been marked for deletion, attempts to access the message will generate an error. To prevent the message from actually being deleted, the application must call the Reset method instead of Disconnect. This will reset the state of the mailbox, preventing any messages that were marked for deletion from actually being removed.

Regardless of whether messages are being searched, downloaded, or removed, keep in mind that in order to access those messages an active connection to the mail server must be established. A consequence of this is that most servers will disconnect sessions that become inactive for too long. In this case, an error would be returned indicating that the connection has been closed. It is generally recommended that applications allow minimal user interaction while retrieving messages. Instead, process each message in the mailbox and then allow the user to review or modify those messages locally, once they have all been downloaded.

Consider a simple routine which retrieves each mail message in a user's mailbox, saves it to a file if the subject contains the word 'failure', and then displays a message box warning the user:

For nMessage = 1 To InternetMail1.LastMessage
    InternetMail1.GetMessage nMessage
    If InStr(1, InternetMail1.Subject, "Failure", vbTextCompare) > 0 Then
       strFileName = "c:\temp\err" & Format(nMessage, "00000") & ".txt"
       InternetMail1.ExportMessage strFileName, mailOptionAllHeaders
       MsgBox "Stored message " & nMessage & " in " & strFileName
    End If
Next

Although this code would appear to execute correctly, the problem is that if the user waits too long to press the OK button on the message box, the session can time-out and the server will drop the connection. When the next iteration of the loop calls the GetMessage method, an error will be returned and the program will fail.

A better implementation would be to download all of the messages, store them, disconnect from the server, and then begin processing them. The simplest approach would be to use a string array in which to store each message as follows:

nMessages = InternetMail1.LastMessage
ReDim strMessage(nMessages)

For nMessage = 1 To nMessages
    InternetMail1.GetMessage nMessage
    strMessage(nMessage) = InternetMail1.Message
Next

InternetMail1.Disconnect

Now that all of the messages are stored in the strMessage array, they can be reloaded into the control by setting the Message property:

For nMessage = 1 To nMessages
    InternetMail1.Message = strMessage(nMessage)
    If InStr(1, InternetMail1.Subject, "Failure", vbTextCompare) > 0 Then
       strFileName = "c:\temp\err" & Format(nMessage, "00000") & ".txt"
       InternetMail1.ExportMessage strFileName, mailOptionAllHeaders
       MsgBox "Stored message " & nMessage & " in " & strFileName
    End If
Next

The one limitation of this approach is that the contents of each message is stored entirely in memory. For very large messages, a better approach would be to store the message in a temporary file and then use the ImportMessage method to load the message into the control, deleting the file when it's no longer needed.

Copyright © 2008 Catalyst Development Corporation. All rights reserved.