Receiving new messages from POP3 server (Part 1)

Getting new messages Summary: Demonstrates how to skip already downloaded messages and retrieve only new messages from the mailbox.

Tutorial map:

Part 1 - Getting new messages
Part 2 - Advanced topics

Typical scenario: The mail client checks whether new messages have arrived since last connection and wants to download new messages (if any).

Limitations: Some old POP3 servers do not support the command required for message search (UIDL command).

How to detect which messages are new

The POP3 protocol has no mechanism to determine whether a message has been already downloaded. Therefore, it's required to keep a list of identifiers of already downloaded messages in a local database maintained by your application.

Any time your application searches the mailbox for new messages, it queries the database for each message in the mailbox to determine if a message has already been downloaded. If the identifier of the particular message has not been found in the database, this message is new.

As the message identifier, Unique-ID can be used.

Message's Unique-ID (UID)

Unique-ID (UID for short) is a unique string assigned to each message in the mailbox. No two messages in the mailbox can have the same Unique-ID value. Sometimes Unique-ID is called GUID (globally unique identifier).

Unique-ID is not associated with "Message-ID:" header of the message.

POP3 object provides Search method which returns array of Unique-IDs of all the messages in the mailbox.

Sample code description

The sample code below receives new messages on RetrieveNewMessages() method call. "Subject:" field of each new message is added to ListBox control named List1.

In real code, the sample function IsNewMessage() should query the database for specified Unique-ID value and return True only if this Unique-ID value is not found in the database. For demo purposes, this function always returns True.

Note: For simplicity, this sample has no error checking. In production code, you should not rely on successful completion of all operations.

Code example:

' This is main function. It retrieves new messages from
' the POP3 server and displays "Subject:" field of each
' retrieved message in the ListBox control.
Sub RetrieveNewMessages()
  Dim objPOP3, objMsg, I

  ' Array of Unique-IDs (taken from the POP3 server)
  Dim arrIDs

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

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

    ' Get Unique-IDs for all the messages in the mailbox
    arrIDs = objPOP3.Search

    ' Iterate through all the messages in the mailbox
    For I = 1 To objPOP3.MessageCount

      ' Search Unique-ID of the message in the database
      If IsNewMessage(arrIDs(I)) Then
      
        ' Download entire message
        Set objMsg = objPOP3.RetrieveSingleMessage(I)
        
        ' Add the message's Subject to the ListBox control
        List1.AddItem objMsg.Subject
      End If
    Next
    objPOP3.Disconnect
  Else
    MsgBox objPOP3.ErrDesc
  End If
End Sub

' This helper function should lookup the ID in the
' database, and then return True if the ID does not
' exist in the list of already downloaded messages.
Function IsNewMessage(ByVal ID)
  ' For demo purposes, the function always returns True.
  IsNewMessage = True
End Function