Volume 1, Issue 3 

Parsing and Accessing Downloaded Message Parts

In the beginning of this article I mentioned that we would be using the EasyMail Message object to do the parsing and decoding.  You may have noticed that we have successfully parsed messages, but have never used the EasyMail Message object.  The reason for this is that the EasyMail POP3 object is fully integrated with the EasyMail Message object.  Beneath the hood the EasyMail POP3 object loads an instance of the EasyMail Message object for each downloaded message.  The EasyMail Message object is responsible for parsing the message and exposing its parts such as its subject, body text, attachments, etc...

Here is a brief sample that demonstrates some of its basic functionality:

set objPOP3 = CreateObject("EasyMail.POP3")
objPOP3.MailServer="mail.domain.com"
objPOP3.Account="account"
objPOP3.Password="password"
objPOP3.Connect
ret = objPOP3.DownloadSingleMessage(1)
if ret>=0 then
   set Message = objPOP3.Messages(1)
   s = "Date: " & Message.Date  & vbcrlf 
   s = s & "From: " & Message.FromAddr  & vbcrlf 
   s = s & "Attachments: " & Message.Attachments.Count
   s = s & vbcrlf  
   s = s & "Subject: " & Message.Subject
   s = s & vbcrlf & vbcrlf 
   s = s & Message.BodyText  
   MsgBox s	
end if

The call to DownloadSingleMessage(1) instructs the EasyMail POP3 object to download the first message in the mailbox.  After the message is downloaded, the DownloadSingleMessage() method internally creates an instance of the EasyMail Message object and adds it to the POP3 object's Messages collection.  Finally DownloadSingleMessage() passes the downloaded data to the new Message object which parses and decodes it.  This all happens with one call to DownloadSingleMessage().

Most of the EasyMail POP3 object's download methods will behave in this way, but there are some methods that download the message to a disk file without parsing.  See DownloadSingleMessageToFile() in the EasyMail Objects documentation for more information.

The EasyMail Message object is extremely fast and powerful.  With it you can get access to every message part including attachments, HTML, etc...  Please see the EasyMail Objects documentation to learn more about the EasyMail Message object and its capabilities. 

Identifying Messages on a POP3 Server

Up until now we have been identifying each message on the server by its message number.  The message number is the message's ordinal position in the mailbox.  i.e. the first (and oldest) message in the mailbox is 1, the second message is 2, etc...  The POP3 protocol is based around this numbering system, but these numbers can change from session to session.  A session in POP3 speak is the period between a connection and disconnection from a mailbox.  POP3 sessions are exclusive.  That is, the POP3 server will only allow one user at a time to be logged on to a specific mailbox.  Message numbers are guaranteed to remain constant within any session.  New messages arriving in the mailbox during a session, will not be available until the next session, and deleted messages are not physically removed until the session is ended.  So POP3 guarantees that message numbers will not change during the course of one single session.

This is relatively simple to understand and does not present any problems until you want operations to span multiple sessions.  Lets say that you want to create an application that downloads messages, stores them on the users hard drive and then disconnects.  Later when the user wants to view the message, they run your app which loads the messages from the hard drive.  When the user wants to perform an operation on a previously downloaded message such as deleting it from the server, your application can connect to the POP3 server easy enough, but the message's ordinal position may have changed since the last session.  So how do you find the message to delete?

To facilitate this type of operation and to assist you in synchronizing application data with a POP3 server, the POP3 server assigns every message a unique-id.  The POP3 RFC (1939) states:

"The unique-id of a message is an arbitrary server-determined string, consisting of one to 70 characters in the range 0x21to 0x7E, which uniquely identifies a message within a [mailbox] and which persists across sessions."

However, the RFC later goes on to state:

"Clients should be able to handle a situation where two identical copies of a message in a [mailbox] have the same unique-id."

So how do you access a message by its unique-id and what do you do if two identical messages in the same mailbox have the same unique-id?  Personally I have not known a mail server to duplicate unique-ids in one mailbox, so I am not going to address that, but you should be aware of it none-the-less.  If you are really concerned, you can add additional checks and processing to handle this situation if it should arise.

The EasyMail POP3 object contains two methods to enable you to work with unique-ids:  GetMessageNumFromID() and GetMessageID().  GetMessageNumFromID() returns a message number given its unique-id.  GetMessageID() does exactly the opposite and returns a unique-id, given a message number.  If your application will need to synchronize its locally stored messages between sessions, it can call GetMessageID() and store the unique-id with the local message data.  Upon subsequent sessions, you can pass that unique-id to GetMessageNumFromID() to retrieve the current message number for that unique-id and thus perform operations on it.

A message's unique-id can also be used to determine if it has already been downloaded by your app during a previous session.  In our example, we want our application to download and store only the new messages that have arrived since our last session.  How do you figure out which messages are new?  POP3 does not support this capability on the server end, but if your app stores the unique-id of each message it has downloaded, you can loop through the mailbox and find any message with a unique-id not stored locally.  These are the new messages.

So you may be asking yourself, "How do you store messages on the local hard drive?" and "How do you delete messages from the server?"  The answer to these questions will come later in this article.

Some applications such as ASP are always disconnected.  A typical ASP POP3 application may logon to the server to download the first 10 headers, display the headers in an HTML table and then disconnect from the POP3 server.  When the user selects a message from the table, the ASP application will have to reconnect to the mailbox and perform an action on the selected message and disconnect again.  This is an example of where using unique-ids works well even though no messages are being stored locally (at least on disk).

Please continue on to learn how to delete messages from the server...

Page Navigator: << Back, 1, 2, 3, 4, 5, Next >>