Receiving message headers from POP3 server (Part 3)

Retrieve a few body lines along with the headers Summary: Demostrates how to get a few lines of the body in addition to message headers when retrieving the list of messages from POP3 server.

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

In some cases, you may need to get somewhat more than just message headers. Often, contents of "From:" and "Subject:" fields don't answer "what is the message about?" question.

Fortunately, RetrieveHeaders and RetrieveSingleMessageHeaders methods support optional parameter BodyLinesCount which specifies how many lines of the body to retrieve in addition to the headers.

The larger BodyLinesCount, bigger piece of the body is returned and more traffic is produced. If BodyLinesCount is larger then actual number of body lines in the message, the entire message is returned. Typically, 20-40 lines of the body describe the message quite enough.

Note: Avoid setting BodyLinesCount to very small values (less than 20). Many e-mail messages have some special (non-textual) information in the first 5-10 lines of the body while the actual body text starts after these lines.

Detailed information on partial messages internals

Note: You may immediatel go to the sample code and skip reading this topic unless you want to deal with partial messages in advanced ways.

For MailBee parser (the module which converts messages into Message objects), there is no difference between entire or partial messages. Available content is fully parsed anyway. Thus, if retrieved piece of the message contains any attachments, they will be parsed and added into Attachments collection but the size and the contents of the attachment will be incorrect if the attachment is not entirely received. Those attachments which didn't fall into the scope of retrieved piece, will not be appended to Attachments collection at all. In other words, MailBee puts into Message object all the information available in the partial message even if the information on some part of the message is incomplete.

So, if you have 1 attachment (named "abc.gif" and sized 1234 bytes) in retrieved partial message, you can guarantee that full message contains AT LEAST one attachment (named "abc.gif") and the size of this attachment is NOT LESS THAN 1234 bytes.

However, if you have 2 attachments in retrieved partial message, you can guarantee that first attachment is retrieved completely and its size and contents correspond to real values. This is due the fact that attachments located in the message and added to Attachments collection sequentially, so each new object guarantees that previous object is finished.

Be aware that text bodies do not behave the same since they often depend on each other while attachments are independent. E.g. retrieved piece contains part of the plain-text body but the message itself is HTML-formatted (its HTML part just did not fall into retrieved piece). Such message will appear as plain-text (BodyFormat=0) or HTML (BodyFormat=1) when retrieved with different BodyLinesCount value.

On other hand, if HTML body is first part and it was partially loaded while plain-text part was not loaded at all (BodyLinesCount is not large), the plain-text part will be generated by MailBee using "HTML-to-plaintext" tool. Increasing BodyLinesCount will cause HTML part to be retrieved completely and plain-text part - partially. Now plain-text body will be taken from partially retrieved plain-text part, not from HTML part plained by MailBee.

Briefly speaking, the information such as body/attachment content or size can be incomplete and greatly dependent on BodyLinesCount value for partial messages.

Note: Message size (Message.Size property) is ALWAYS correct even if only message headers are retrieved. MailBee gets the message size using special POP3 command.

Sample code description

The sample code below gets message headers + 100 first lines of the body part and adds first line of the text body to ListBox control. The sample performs this for each message in the mailbox.

Code example:

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

Dim objPOP3, objMsg, colMsgs

' First line of the text body
Dim strLine

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 + 100 body lines
  Set colMsgs = objPOP3.RetrieveHeaders(1, -1, 100)

  If objPOP3.IsError Then
    ' Handle errors
    MsgBox "Error #" & objPOP3.ErrCode & ", " & objPOP3.ErrDesc
  Else
    For Each objMsg In colMsgs

      ' Store available body text lines in the variable
      strLine = objMsg.BodyText

      ' Keep only 1 line of all available body text 
      If InStr(strLine, vbCrLf) > 0 Then
        strLine = Left(strLine, InStr(strLine, vbCrLf))
      End If

      ' Add first line of the body to ListBox
      List1.AddItem strLine
    Next
  End If

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