Retrieving Messages

Mail messages are stored on a mail server in a mailbox, typically a folder or single file which contains all of the messages for a specific user. As new messages arrive for the user they are added to the mailbox and they are removed as they are read and deleted. The first step in retrieving messages from a user's mailbox is establishing a network connection with the mail server and authenticating that connection with a user name and password. This can be done using the Connect method, which has a number of optional arguments:

Constant	Description
ServerName	An optional string value which specifies the domain name or IP address of the mail server. If this argument is not specified, the value of the ServerName property is used instead.
ServerPort	An optional integer value which specifies the port number to use when establishing a connection with the server. If this argument is not specified, the value of the ServerPort property is used instead. A value of zero means that the default port for the server should be used.
UserName	An optional string value which specifies the user name is required to authenticate access to the mailbox. If this argument is not specified, the value of the UserName property is used instead.
Password	An optional string value which specifies the password which is required to authenticate access to the mailbox. If this argument is not specified, the value of the Password property is used instead.
Timeout	An optional integer value which specifies the amount of time in seconds that the control will wait for an operation to complete before returning an error. If this argument is not specified, the value of the Timeout property is used. The default timeout period is sixty (60) seconds.
Options	An optional integer value which specifies one or more options as bit flags. If this argument is not specified, the value of the Options property is used instead. The most common option that is used is mailOptionAPOP which indicates that APOP authentication should be used instead of standard user authentication when connecting to the mail server. Refer to the technical reference for information about the other options that are available.

The following code demonstrates connecting to a mail server:

Dim nError As Long
Dim nMessages As Long

nError = InternetMail1.Connect(editServerName.Text, , _
                               editUserName.Text, _
                               editPassword.Text)

If nError Then
    MsgBox "Unable to connect to " & editServerName.Text & vbCrLf & _
           InternetMail1.LastErrorString, vbExclamation
    Exit Sub
End If

As with most of the other control methods, Connect returns an error status if the connection has failed or a value of zero if it was successful. Once a connection with the mail server has been established, you can list the available messages by setting the MessageIndex property. For example, the following code would check to make sure that there are messages in the mailbox, and if so, add the subject of each message to a listbox:

If InternetMail1.LastMessage = 0 Then
    MsgBox "The mailbox is currently empty", vbInformation
    InternetMail1.Disconnect
    Exit Sub
End If

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

When the MessageIndex property is set, the headers for the specified message are retrieved from the mail server and can be accessed using the control's properties. However, the entire message contents are not retrieved unless the GetMessage method is called. This allows applications to retrieve message headers without the requirement that the complete message be downloaded. For example, the following code would check to see if a message has attachments by checking the Content-Type header:

For nMessage = 1 To InternetMail1.LastMessage
    InternetMail1.MessageIndex = nMessage
    If InStr(InternetMail1.ContentType, "multipart/mixed") Then

        ' This is a multipart/mixed message, so it is likely
        ' that it contains one or more file attachments

        List1.AddItem InternetMail1.Subject
    End If
Next

The GetMessage method will retrieve the complete message including the headers, message body and any attachments. Immediately after the GetMessage method is called, the OnProgress event will begin to fire, enabling an application to update the user interface. As with most of the other methods, once the message has been retrieved, GetMessage will return a value of zero if it was successful or an error code if a problem was encountered. The following example demonstrates how GetMessage and ExportMessage can be used to save messages to the local system:

For nMessage = 1 To InternetMail1.LastMessage
    strFileName = "c:\temp\msg" & Format(nMessage, "00000") & ".txt"

    ' Retrieve the message from the server

    nError = InternetMail1.GetMessage(nMessage)
    If nError Then Exit For

    ' Export the message to a file on the local system

    nError = InternetMail1.ExportMessage(strFileName)
    If nError Then Exit For
Next

If nError Then
    MsgBox "Unable to retrieve or store message " & nMessage & vbCrLf & _
           InternetMail1.LastErrorString, vbExclamation
    Exit Sub
End If

An alternate method of storing messages in files on the local system is to use StoreMessage instead of GetMessage and ExportMessage. The most significant difference between the two approaches is that the StoreMessage method does not change the contents of the current message. Instead, it simply retrieves the message from the server and stores it in the specified file. The previous example could be re-written as:

For nMessage = 1 To InternetMail1.LastMessage
    strFileName = "c:\temp\msg" & Format(nMessage, "00000") & ".txt"

    ' Store the message from the server

    nError = InternetMail1.StoreMessage(nMessage, strFileName)
    If nError Then Exit For
Next

If nError Then
    MsgBox "Unable to store message " & nMessage & vbCrLf & _
           InternetMail1.LastErrorString, vbExclamation
    Exit Sub
End If

It is important to keep in mind that while the application is connected to the mail server, the mailbox is in a locked state which prevents any other clients from accessing it. For this reason, it is recommended that any significant message processing be done on local copies of the messages.