Receiving message headers from POP3 server (Part 1)

Downloading the list of messages Summary: Demonstrates using POP3 object for building messages' list without downloading entire messages.

Tutorial map:
Part 1 - Downloading the list of messages
Part 2 - Detecting attachments
Part 3 - Retrieve a few body lines along with the headers

Many e-mail applications give users ability to select the messages to be retrieved from the list of messages available in the mailbox on the server. To build this list it's required to get some preview information on each message in the mailbox. For POP3, this information is message header.

Retrieving headers for all the messages in the mailbox

RetrieveHeaders method of POP3 object retrieves headers for all messages in the mailbox, and returns Messages collection which represents message list (if an error occurs, returned value is Nothing). Messages are returned in the same order they are located in the mailbox: first message is oldest, last is newest.

The sample code below fills ListBox control with "From:" fields of all messages in the mailbox. It's assumed VB form already contains ListBox control named List1.

Code example:

' You can place the code below into any Sub or Function of your app

Dim objPOP3, objMsg, colMsgs

Set objPOP3 = CreateObject("MailBee.POP3")
objPOP3.LicenseKey = "put your license key here"

' Connect to POP3 server
If objPOP3.Connect("mail.server.com", 110, "user", "pass") Then

  ' Download headers for all messages
  Set colMsgs = objPOP3.RetrieveHeaders

  If objPOP3.IsError Then
    ' Handle errors
    MsgBox "Error #" & objPOP3.ErrCode & ", " & objPOP3.ErrDesc
  Else
    For Each objMsg In colMsgs
      ' Add "From:" to ListBox
      List1.AddItem objMsg.FromAddr
    Next
  End If

  objPOP3.Disconnect
Else
  ' Handle errors
  MsgBox "Error #" & objPOP3.ErrCode & ", " & objPOP3.ErrDesc
End If

Reverse-order iterating through the collection of retrieved headers

It's often required to display messages in the order different from the order they appear in the returned collection. Another case is when you need to learn index of particular message for further processing (e.g. delete particular message from the server).

To iterate through the collection in arbitrary way, you can use For..To..Step syntax instead of simple but not flexible For..Each one.

The sample code below differs from the previous sample in that it fills ListBox control in reverse order (from newest to oldest) using For..To..Step syntax. Additionally, it deletes from the mailbox the messages having "remove" word in the "Subject:" field.

Code example:

' You can place the code below into any Sub or Function of your app

Dim objPOP3, colMsgs, I

Set objPOP3 = CreateObject("MailBee.POP3")
objPOP3.LicenseKey = "put your license key here"

' Connect to POP3 server
If objPOP3.Connect("mail.server.com", 110, "user", "pass") Then

  ' Download headers for all messages
  Set colMsgs = objPOP3.RetrieveHeaders

  If objPOP3.IsError Then
    ' Handle errors
    MsgBox "Error #" & objPOP3.ErrCode & ", " & objPOP3.ErrDesc
  Else
    For I = colMsgs.Count To 1 Step -1

      ' Add "From:" to ListBox
      List1.AddItem colMsgs(I).FromAddr


      If colMsgs(I).Subject = "remove" Then
        ' Delete message with "remove" in Subject
        objPOP3.DeleteMessage I
      End If
    Next
  End If
  objPOP3.Disconnect
Else
  ' Handle errors
  MsgBox "Error #" & objPOP3.ErrCode & ", " & objPOP3.ErrDesc
End If

Retrieving headers for the particular message

Sometimes you might need to download headers for particular messages only. Common cases are:

the mailbox contains large number of messages (hundreds or thousands), and you want to download only 10-20 headers (usually for displaying message list on per-page basis);
specific needs of your task. For example, your application uses some kind of database to maintain messages, and only new messages should be searched and/or received;
some messages were marked for deletion (using DeleteMessage method) and become unretrievalable. Presence of such messages will cause RetrieveHeaders to fail. Note that messages marked for deletion will be permanently deleted once Disconnect method is called, so you will never face the issue above if you never attempt to retrieve messages after marking some of them for deletion.

You can retrieve headers for single message using RetrieveSingleMessageHeaders method.

The sample code below fills ListBox control with "From:" fields of K messages starting from message number N. For example, if N = 1, first K message headers are retrieved; if N = 21, K = 10 and there are 30 or more messages available, message headers from 21 to 30 will be retrieved. If N = 21, K = 10 but only 25 messages exist in the mailbox, message headers from 21 to 25 will be retrieved. Messages are returned in direct order (i.e. assumed that N = 1 corresponds to the first message in the mailbox).

Code example:

' You can place the code below into any Sub or Function of your app

Dim objPOP3, objMsg, I, N, B1, B2, K

Set objPOP3 = CreateObject("MailBee.POP3")
objPOP3.LicenseKey = "put your license key here"

' Connect to POP3 server
If objPOP3.Connect("mail.server.com", 110, "user", "pass") Then

  ' Start from message #21
  N = 21

  ' Retrieve 10 message headers: from #21 to #30
  K = 10

  ' Lower boundary of the range to retrieve
  B1 = N

  ' Upper boundary of the range to retrieve
  B2 = N + K - 1

  ' Limit upper boundary by ordinal position
  ' of the last message in the mailbox
  If B2 > objPOP3.MessageCount Then
    B2 = objPOP3.MessageCount
  End If

  ' Loop through messages in the specified range
  For I = B1 To B2

    ' Get message headers
    Set objMsg = objPOP3.RetrieveSingleMessageHeaders(I)

    If objPOP3.IsError Then
      ' Handle errors
      MsgBox "Error #" & objPOP3.ErrCode & ", " & objPOP3.ErrDesc
    Else
      ' Add "From:" to ListBox
      List1.AddItem objMsg.FromAddr 
    End If
  Next

  objPOP3.Disconnect
Else
  ' Handle errors
  MsgBox "Error #" & objPOP3.ErrCode & ", " & objPOP3.ErrDesc
End If