PopClient - A POP3 companion to SmtpClient

• Download source code (including VS 2010 demo project) - 60 Kb

Introduction

I needed a POP3 library for a .NET project that a friend and I were working on, and while a quick Google-search revealed several free implementations, none of them fully fit my requirements. I wanted a reliable POP3 class with full support for asynchronous fetching, cancellation, SSL, attachments, HTML email, and an uncomplicated and simple interface so that calling applications wouldn't need to do hideous workarounds to integrate it into their existing system. This article explains how this library can be used, talks about the class implementation, and also includes a demo WPF application that shows how a typical app might use this library.  This library's goal is to provide developers with a very simple way to read email from POP3 servers, and with that in mind, it hides the underlying POP3 protocol from calling code. What that means is that this library is not for those who are writing their own POP3 based code or want to extend the POP3 protocol in some way (for example writing a spam filter or an email auto-forwarding application). In some ways this library can be considered as a POP3 analogy to the SmtpClient class from the System.Net.Mail namespace and in fact it actually uses the MailMessage class (from the same namespace) to represent an email (although that had its disadvantages as I will explain in this article).

Safety note about the demo app

The PopClient class has a DeleteMailAfterPop property that's used to specify whether mails should be left on the server or if they should be deleted after they are fetched. Unless it's a throwaway POP account, chances are extremely low that you'd want to delete mails when running the demo app, and so as a precautionary measure, that property has been disabled both in the UI and in the code, so you will not inadvertently delete any of your email.

VS 2010 and .NET 4.0

While the code and the the demo project has been written and tested using VS 2010 and .NET 4.0, you should not have too much difficulty using this from VS 2008 and .NET 3.5. As far as I know, I have not used any 4.0 specific features in any of the code.

Using the library

All the code is in the PopClient assembly, so you need to add a reference to that. And all the public classes are under the

Extra.Mail

namespace, so you may want to add a using declaration in your code for that namespace. The PopClient class is the only class that you need to directly instantiate and use, and it implements IDisposable and it's important that you dispose it off when you are finished with the class. That said, since the class fetches mail asynchronously, you should not dispose off the class until either the mail fetch operation has completed, or you have manually aborted the mail fetch operation. This basically means that it's not the best suited class for an using-block (typically used for IDisposable types). The demo app shows one typical way that the class be be disposed, and I'll also discuss another simple way to dispose off the instance safely. Ironically, after saying all this, the first bit of code I am about to show you does use an using-block, although this is a console application and I take precautions to ensure that the object stays alive until the POP3 operation has completed.

static void Main()
{
    using (var popClient = new PopClient(host, port) { 
        Username = username, Password = password, EnableSsl = true })
    {
        popClient.MailPopCompleted += PopClient_MailPopCompleted;
        popClient.MailPopped += PopClient_MailPopped;
        popClient.QueryPopInfoCompleted += PopClient_QueryPopInfoCompleted;
        popClient.ChatCommandLog += PopClient_ChatCommandLog;
        popClient.ChatResponseLog += PopClient_ChatResponseLog;

        try
        {
            popClient.PopMail();
        }
        catch(PopClientException pce)
        {
            Console.WriteLine("PopClientException caught!");
            Console.WriteLine(
                "PopClientException.PopClientBusy : {0}", pce.PopClientBusy);
        }

        Console.ReadKey();
    }
}

The class is instantiated with the required POP3 settings such as host, username, and password. I have also hooked onto several events which will be fired asynchronously during the POP3 fetch operation. Once this is all done, a call is made to the PopMail method (which immediately returns), and it's called from a try-catch block since the method can throw exceptions. Although the code above only catches a

PopClientException

be aware that it can also throw an

InvalidOperationException

(the demo app handles both). And finally notice the crafty positioning of the Console.ReadKey call to keep the object alive and un-disposed until the fetch is completed. The ChatXXXLog events basically log protocol-chat used for the POP3 connection, with the

ChatCommandLog

firing for all commands we send to the server and the ChatResponseLog firing for all single-line server responses (for usability reasons, I do not log multi-line responses, since that will quickly be unmanageable when fetching large emails with bulky attachments). It's purely optional to handle these events and their use is primarily to diagnose connectivity issues, although you could also follow the chat log to get an idea of how POP3 chat is executed (it's a very simple protocol, so it's doubtful that anyone will want to do it for that purpose more than once or twice).

static void PopClient_ChatResponseLog(object sender, PopClientLogEventArgs e)
{
    Console.WriteLine("<< {0}", e.Line);
}

static void PopClient_ChatCommandLog(object sender, PopClientLogEventArgs e)
{
    Console.WriteLine(">> {0}", e.Line);
}

 The effect of those two handlers is to give you a full chat conversation (with beautiful TCP direction indicators in text). *grin*

>> STAT
<< +OK 7 703466
>> LIST 1
<< +OK 1 243160
>> UIDL 1
<< +OK 1 717619000000008003
>> RETR 1
<< +OK
>> LIST 2
<< +OK 2 2
>> UIDL 2
<< +OK 2 717619000000009001
>> RETR 2
<< +OK
>> LIST 3
<< +OK 3 216991
>> UIDL 3
<< +OK 3 717619000000010001
>> RETR 3
<< +OK
>> LIST 4
<< +OK 4 12
>> UIDL 4
<< +OK 4 717619000000011001
>> RETR 4
<< +OK

The WPF demo app shows a better way to show this information. The other three events are what you really need to handle for reading the fetched emails. The first one to fire will be the QueryPopInfoCompleted event, which gives you the number of emails and their total size. You can potentially use this information to show a progress-bar or to update a summary status UI panel.

static void PopClient_QueryPopInfoCompleted(object sender, MailPopInfoFetchedEventArgs e)
{
    Console.WriteLine("Event Fired: QueryPopInfoCompleted");
    Console.WriteLine("Count: {0}, Total Size: {1} bytes", e.Count, e.Size);
}

Next, the MailPopped event fires once for each mail that's retrieved, so if you've handled the QueryPopInfoCompleted event you will know how many times this will fire (unless you cancel the operation with a call to Cancel()). The Class Reference section details all the information, arguments,  and properties that are available, so I will not explain every single item in the code, although the property names are fairly self descriptive, so anyone writing code to fetch email probably won't need to look at the documentation.

static void PopClient_MailPopped(object sender, MailPoppedEventArgs e)
{
    Console.WriteLine("Event Fired: MailPopped");
    Console.WriteLine("Mail No. {0}", e.Index);
    Console.WriteLine("Size: {0}", e.Size);
    Console.WriteLine("Uidl: {0}", e.Uidl);
    Console.WriteLine("Received: {0}", e.ReceivedTime);
    Console.WriteLine("From: {0}, {1}", e.Message.From.Address, e.Message.From.DisplayName);
    Console.WriteLine("To: {0}", e.Message.To);
    Console.WriteLine("Subject: {0}", e.Message.Subject);
    Console.WriteLine("Attachments: {0}", e.Message.Attachments.Count);
    
    foreach (var attachment in e.Message.Attachments)
    {
        Console.WriteLine("File: {0}", attachment.Name);
    }

    for (int i = 0; i < e.Message.Headers.Count; i++)
    {
        Console.WriteLine("{0} = {1}", 
            e.Message.Headers.GetKey(i), 
            new String(e.Message.Headers[i].Take(40).ToArray()));
    }
}

The MailPoppedEventArgs.Message property is of type

MailMessage

, so anyone who's used that class before will recognize the other properties that I've used there. The developers who wrote

MailMessage

intended it primarily for the SmtpClient class, which meant that it does not have certain properties that you need when you are retrieving mail, such as Uidl, ReceivedTime,

Size

etc. So I had to provide them though the MailPoppedEventArgs class. I realized this only after I had written half the code and while it would not have been terribly difficult to write my custom MailMessage-like class, I decided to continue using MailMessage, largely out of my inconsiderate need to ensure that my class remained analogous and similar to the SmtpClient class which used MailMessage. Developers like familiarity and I believe that using recognizable types will certainly help with that. I also added an extension method to the Attachment class so that you won't have to mess with memory streams and file IO, and instead can just call a nice Save(filePath) method that will save the attachment (the WPF demo app does make use of this). The last event that's fired is the MailPopCompleted event. Note that this is always fired, whether the POP fetch completed harmoniously, or if it got user cancelled, or even if it had to abort because of an exception. In fact it's the only way to be notified of unexpected errors, so you should always handle this event.

static void PopClient_MailPopCompleted(object sender, MailPopCompletedEventArgs e)
{
    Console.WriteLine("Event Fired: MailPopCompleted");
    Console.WriteLine("MailPopCompletedEventArgs.Aborted : {0}", e.Aborted);
    if (e.Exception != null)
    {
        Console.WriteLine(e.Exception.Message);

        PopClientException pce = e.Exception as PopClientException;
        if(pce != null)
        {                    
            Console.WriteLine("PopClientException.PopClientUserCancelled : {0}", 
                pce.PopClientUserCancelled);
        }
    }            
}

This code does not fully demonstrate how the PopClientException can be used to determine POP3 errors (like a bad password, or a POP3 server error), but the demo app does a better job with that.

Retrieving only new messages

• Support for retrieving only new messages was added in the November 19th 2010 update.

If you've noticed with mail clients that have an option to leave mail on the server, they only retrieve mail that has not been previously fetched. They achieve this by storing the UIDL values for each mail message and then not downloading messages that match an existing UIDL. The PopClient class now has a collection property called UidlsToIgnore. So prior to calling PopMail, the calling client can optionally populate this collection and those messages will be skipped. Changes have been made to the library so that the count and total size reported will be adjusted to accommodate these skipped messages. Be aware though that the index value provided by the MailPoppedEventArgs class will continue to represent the index value of the message in the mail server. So you will potentially see non-contiguous indices when fetching mail if you have opted to skip existing messages. This is not a bug and is correct behavior. Example code showing how skip-UIDLs are added:

popClient.UidlsToIgnore.Add("717619000000008003");
popClient.UidlsToIgnore.Add("717619000000009001");
popClient.UidlsToIgnore.Add("717619000000010001");

Warning : Event handlers and thread context

One very important thing to keep in mind is that all the events except for the MailPopCompleted event are fired on a different thread (the worker thread that the class internally uses for the POP3 connection). So if you are handling UI from these event handlers, you need to take the typical precautions that you need to take when accessing UI controls from auxiliary threads. There are well-known methods to work around this where the events can be made to fire on the same thread that created the PopClient object, but I decided not to go that route for two specific reasons. The first reason is that this forces the PopClient class to be aware of such UI/threading issues and I wanted to keep the class design clean which meant that it had to be kept unaware of such frivolous side effects. A second important reason is that whether the calling code uses Windows Forms or WPF would dictate the need to handle thread context in distinct ways, not to mention that the class may be used from other .NET UI frameworks which may have their own thread related quirks. A third minor reason is that it may actually be a hazardous approach to hide this from the caller by attempting to handle this in the

PopClient

class, since the caller will remain blissfully unaware of these threading issues and will thus be unprepared to deal with any potential consequences arising out of inter-thread access. And finally, as you will see from the demo project, it's quite trivial to handle this in the calling UI code.

The demo application

The WPF demo application was written using Visual Studio 2010 and targets the .NET 4.0 framework. I will completely refrain from discussing the XAML code here and will instead focus on how the PopClient class is typically used in a UI application. Those of you who are interested in the XAML/data-binding can go through the project source, and if you have specific questions (unlikely given how simple the code is), please feel free to ask me through the forum for this article. The demo project uses MVVM and all of the PopClient code is in a single View-Model class. Every method that I discuss below will thus be a part of this class.

The View-Model has a PopClient field (needs to be a field, so we can support cancellation and disposing). Note that the socket connection is not established when you instantiate the class (not surprising since it does not have connection info yet).

private PopClient popClient = new PopClient();

The event handlers are hooked up in the V-M constructor.

public MainWindowViewModel()
{
    popClient.QueryPopInfoCompleted += PopClient_QueryPopInfoCompleted;
    popClient.MailPopped += PopClient_MailPopped;
    popClient.MailPopCompleted += PopClient_MailPopCompleted;
    popClient.ChatCommandLog += PopClient_ChatCommandLog;
    popClient.ChatResponseLog += PopClient_ChatResponseLog;

    Application.Current.Exit += Current_Exit;
}

void Current_Exit(object sender, ExitEventArgs e)
{
    popClient.Dispose();
}

In addition, I also handle the application's Exit event so I can dispose off the popClient instance. Technically this can be considered a superficial thing to do since the process will have terminated and all process-specific resources would be released. But it keeps the code clean and encourages this practice in applications where the V-M may be created and destroyed multiple times during the life of an application (in which case, the V-M itself should probably be an IDisposable). It's a little easier with WinForms since all Controls and Forms are

IDisposable

, and thus there's a documented well-established place to dispose the PopClient instance. WPF windows don't do it that way, since the WPF approach of using weak references everywhere makes this unnecessary. One alternate way to dispose off the PopClient instance is in the MailPopCompleted event handler although it is not a very clean approach and is a bit of a hack. I say that because when the event fires, the PopClient instance is still in use, so for a few microseconds you actually have a disposed object that's still executing a method (albeit its last one). Of course since I wrote the class, I know it's safe to do this (as of today) and there's no risk of the GC firing when it's still not done executing a method, but if you run code profilers or memory leak analyzers, they may complain and throw up an agitated warning message. So I wouldn't recommend doing this unless it's in code that you are in full control of.

The following fields are used to propagate information to the UI, namely the main window and the log window. The LogInfo class is merely a convenience class I created to help with data-binding. One important member here is the mainDispatcher field which is used to handle the thread context issues arising from how the events are fired on secondary threads (and not from the main UI thread where the handlers were originally setup from).

private Dispatcher mainDispatcher;

private ObservableCollection<MailPoppedEventArgs> mails
  = new ObservableCollection<MailPoppedEventArgs>();

class LogInfo
{
    public string Line { get; set; }
    public bool Response { get; set; }
}

private ObservableCollection<LogInfo> logs
  = new ObservableCollection<LogInfo>();

The RefreshCommand property is a command object exposed by the V-M that basically performs the mail-fetch operation.

public ICommand RefreshCommand
{
    get
    {
        return refreshCommand ??
          (refreshCommand = new DelegateCommand(Refresh, CanRefresh));
    }
}

public bool CanRefresh()
{
    return !popClient.IsWorking();
}

public void Refresh()
{
    popClient.Host = Settings.Default.Host;
    popClient.Port = Settings.Default.Port;
    popClient.Username = Settings.Default.Username;
    popClient.Password = this.PopPassword;
    popClient.EnableSsl = Settings.Default.EnableSsl;
    popClient.DeleteMailAfterPop = false; // For demo safety!
    popClient.Timeout = Settings.Default.Timeout;

    try
    {
        mainDispatcher = Dispatcher.CurrentDispatcher;
        FetchStatusText = "Fetching...";
        mails.Clear();
        logs.Clear();
        popClient.PopMail();
    }
    catch (InvalidOperationException ex)
    {
        FetchStatusText = String.Format(
          "Connection error - {0}", ex.Message);
    }
    catch (PopClientException ex)
    {
        FetchStatusText = String.Format(
          "POP3 error - {0}", ex.Message);
    }
}

Notice how CanRefresh delegates the call to

PopClient.IsWorking

which will return true if a fetch operation is current under way. I assign the various POP3 properties that are required for a POP3 connection here, although for this particular demo project this was actually a mistake to do this here - since it gets called every time Refresh is called. Originally I had planned to allow the user to change POP settings after a fetch, but eventually I ended up showing the settings dialog only once, at startup. Of course that's a rather insignificant issue, but I thought I'd mention that here in case someone wonders why I did it that way. Notice how I save the current Dispatcher instance in the mainDispatcher field, this is what I'll use later to update my ObservableCollection<>s because they will be bound to the View and will thus need to execute on the UI thread.

Cancelling is fairly straightforward.

public ICommand CancelCommand
{
    get
    {
        return cancelCommand ?? 
          (cancelCommand = new DelegateCommand(Cancel, CanCancel));
    }
}

public bool CanCancel()
{
    return popClient.IsWorking();
}

public void Cancel()
{
    popClient.Cancel();
}

There is a potential race condition where CanCancel returns true, but the fetch operation completes before Cancel is called. But it's safe to call Cancel even in that scenario, so there's no need to handle that race condition.

Here's the code that's used to save an attachment (this is accessible via the context menu on attachment icons).

public ICommand SaveFileCommand
{
    get
    {
        return saveFileCommand ?? 
          (saveFileCommand = new DelegateCommand<Attachment>(SaveFile));
    }
}

public void SaveFile(Attachment attachment)
{
    SaveFileDialog dialog = new SaveFileDialog()
    {
        FileName = attachment.Name
    };

    if (dialog.ShowDialog().GetValueOrDefault())
    {
        attachment.Save(dialog.FileName);
    }
}

The Save method is an extension method I wrote on the

Attachment

class. Here's the code that brings up the Chat-Log window.

public ICommand ShowChatLogCommand
{
    get
    {
        return showChatLogCommand ?? 
          (showChatLogCommand = new DelegateCommand(
            ShowChatLog, CanShowChatLog));
    }
}

private LogWindow logWindow;

public bool CanShowChatLog()
{
    return logWindow == null;
}

public void ShowChatLog()
{
    logWindow = new LogWindow() 
      { DataContext = logs, Owner = Application.Current.MainWindow };
    logWindow.Show();
    logWindow.Closed += (s,e) => logWindow = null;
}

As you can see it uses the logs collection, which is populated via the ChatXXXLog event handlers.

void PopClient_ChatResponseLog(object sender, PopClientLogEventArgs e)
{
    mainDispatcher.Invoke((Action)(() => logs.Add(
      new LogInfo() { Line = e.Line, Response = true })), null);
}

void PopClient_ChatCommandLog(object sender, PopClientLogEventArgs e)
{
    mainDispatcher.Invoke((Action)(() => logs.Add(
      new LogInfo() { Line = e.Line })), null);
}

Notice how I use mainDispatcher to invoke my code on the UI thread. Here are the event handlers for the QueryPopInfoCompleted and MailPopped events.

void PopClient_MailPopped(object sender, MailPoppedEventArgs e)
{
    mainDispatcher.Invoke((Action)(() => mails.Add(e)), null);
}

void PopClient_QueryPopInfoCompleted(
  object sender, MailPopInfoFetchedEventArgs e)
{
    MailStatsText = String.Format(
      "{0} mails, Size = {1}", e.Count, e.Size);
}

And, here's the event handler for the MailPopCompleted event.

void PopClient_MailPopCompleted(object sender, MailPopCompletedEventArgs e)
{
    if (e.Aborted)
    {
        PopClientException popex = e.Exception as PopClientException;
        if (popex == null)
        {
            FetchStatusText = "Aborted!";
        }
        else
        {
            FetchStatusText = popex.PopClientUserCancelled 
              ? "User cancelled!" :  
                String.Format("POP3 error - {0}", popex.Message);
        }
    }
    else
    {
        FetchStatusText = "Done!";
    }

    CommandManager.InvalidateRequerySuggested();
}

The code here is a better example of how the various exceptions are handled (compared to the code I showed earlier). It demonstrates how the application can handle POP3 server errors and display those messages back to the user.

Class Reference

All public types are in the Extra.Mail namespace.

PopClient Class

public class PopClient : IDisposable
{
    // Summary:
    //     Initializes a new instance of the PopClient class.
    public PopClient();

    //
    // Summary:
    //     Initializes a new instance of the PopClient class.
    //
    // Parameters:
    //   host:
    //     The name or IP address of the host server
    public PopClient(string host);

    //
    // Summary:
    //     Initializes a new instance of the PopClient class.
    //
    // Parameters:
    //   host:
    //     The name or IP address of the host server
    //
    //   port:
    //     The port to be used
    public PopClient(string host, int port);

    // Summary:
    //     Specify whether email is deleted after fetch
    public bool DeleteMailAfterPop { get; set; }

    //
    // Summary:
    //     Specify whether the PopClient uses a Secure Sockets Layer connection
    public bool EnableSsl { get; set; }

    //
    // Summary:
    //     Gets or sets the name or IP address of the POP3 host
    public string Host { get; set; }

    //
    // Summary:
    //     Gets or sets the POP3 password
    public string Password { get; set; }

    //
    // Summary:
    //     Gets or sets the port used for the POP3 connection
    public int Port { get; set; }

    //
    // Summary:
    //     Gets or sets a value that specifies the amount of time after the connection
    //     times out.
    public int Timeout { get; set; }

    //
    // Summary:
    //     Gets or sets the POP3 username
    public string Username { get; set; }

    /// <summary>
    /// Gets or sets the collection of UIDLs that are to be ignored when doing a fetch.
    /// </summary>    
    public HashSet<string> UidlsToIgnore { get; private set; }

    // Summary:
    //     Occurs when a POP3 command is sent to the server
    public event EventHandler<PopClientLogEventArgs> ChatCommandLog;

    //
    // Summary:
    //     Occurs when a POP3 response is received from the server
    public event EventHandler<PopClientLogEventArgs> ChatResponseLog;

    //
    // Summary:
    //     Occurs when the asynchronous fetch completes
    public event EventHandler<MailPopCompletedEventArgs> MailPopCompleted;

    //
    // Summary:
    //     Occurs when a mail is fetched
    public event EventHandler<MailPoppedEventArgs> MailPopped;

    //
    // Summary:
    //     Occurs when summary info for the fetch operation is available
    public event EventHandler<MailPopInfoFetchedEventArgs> QueryPopInfoCompleted;

    // Summary:
    //     Cancels the asynchronous fetch operation
    public void Cancel();

    //
    // Summary:
    //     Releases all resources used by the PopClient class.
    public void Dispose();

    //
    // Summary:
    //     Indicates whether a fetch operation is under way
    //
    // Returns:
    //     True if a fetch is on, False otherwise
    public bool IsWorking();

    //
    // Summary:
    //     Begins an asynchronous fetch operation
    public void PopMail();
}

PopClientException Class

[Serializable]
public class PopClientException : Exception
{
    // Summary:
    //     Initializes a new instance of the PopClientException class.
    public PopClientException();
    
    //
    // Summary:
    //     Initializes a new instance of the PopClientException class.
    //
    // Parameters:
    //   message:
    //     The message that describes the error
    public PopClientException(string message);

    // Summary:
    //     Gets a value indicating whether the PopClient is busy.
    public bool PopClientBusy { get; }
    
    //
    // Summary:
    //     Gets a value indicating whether the fetch operation was cancelled by the
    //     user.
    public bool PopClientUserCancelled { get; }

    // Summary:
    //     Initializes a new instance of the PopClientException class.
    //
    // Parameters:
    //   info:
    //     The object that holds the serialized object data
    //
    //   context:
    //     The contextual information about the source or destination
    public override void GetObjectData(SerializationInfo info, StreamingContext context);
}

MailPopInfoFetchedEventArgs Class

public class MailPopInfoFetchedEventArgs : EventArgs
{
    // Summary:
    //     Instantiates a new instance of the MailPopInfoFetchedEventArgs class
    //
    // Parameters:
    //   count:
    //     The number of messages
    //
    //   size:
    //     Total size of all messages
    public MailPopInfoFetchedEventArgs(int count, int size);

    // Summary:
    //     Get the number of messages
    public int Count { get; }
    //
    // Summary:
    //     Gets the total size of all messages
    public int Size { get; }
}

MailPoppedEventArgs Class

public class MailPoppedEventArgs : EventArgs
{
    // Summary:
    //     Instantiates a new instance of the MailPoppedEventArgs class
    //
    // Parameters:
    //   index:
    //     The index of the message
    //
    //   message:
    //     A MailMessage that contains the fetched message
    //
    //   size:
    //     The size of the mail
    //
    //   uidl:
    //     The uidl value of the message
    //
    //   receivedTime:
    //     Time when the message was received by the server
    public MailPoppedEventArgs(
      int index, MailMessage message, int size, string uidl, DateTime receivedTime);

    // Summary:
    //     Gets the index of the message
    public int Index { get; }
    //
    // Summary:
    //     Gets the MailMessage that contains the fetched message
    public MailMessage Message { get; }
    //
    // Summary:
    //     Gets the time when the message was received by the server
    public DateTime ReceivedTime { get; }
    //
    // Summary:
    //     Gets the size of the mail
    public int Size { get; }
    //
    // Summary:
    //     Gets the uidl value of the message
    public string Uidl { get; }
}

MailPopCompletedEventArgs Class

public class MailPopCompletedEventArgs : EventArgs
{
    // Summary:
    //     Instantiates a new instance of the MailPopCompletedEventArgs class
    public MailPopCompletedEventArgs();
    //
    // Summary:
    //     Instantiates a new instance of the MailPopCompletedEventArgs class
    //
    // Parameters:
    //   ex:
    //     Any exception that was thrown during the asynchronous fetch
    public MailPopCompletedEventArgs(Exception ex);

    // Summary:
    //     Gets a value indicating whether the fetch operation was aborted
    public bool Aborted { get; }
    //
    // Summary:
    //     Gets any exception that was thrown during the asynchronous fetch
    public Exception Exception { get; }
}

PopClientLogEventArgs Class

public class PopClientLogEventArgs : EventArgs
{
    // Summary:
    //     Instantiates a new instance of the PopClientLogEventArgs class
    //
    // Parameters:
    //   line:
    //     A string representing a message log line
    public PopClientLogEventArgs(string line);

    // Summary:
    //     Gets a string representing a message log line
    public string Line { get; }
}

Implementation details

This class is based on the POP3 protocol which is standardized via RFC1939 (Post Office Protocol v3).

• POP3 RFC (1939) on faqs.org

One of the design intentions was to hide the implementation details from the public interface and this meant that I could opt to selectively implement the minimal protocol needed to fetch email from a POP3 server without losing out on any POP3 functionality. The internal class PopConnection is used to establish a socket connection and to send/receive POP3 commands and responses from a server. It's a very thin socket based class that uses a

TcpClient

object to communicate with a POP server.

internal class PopConnection : IDisposable
{
    private char[] endMarker;
    
    private Stream stream;
    
    private TcpClient tcpClient;

    public PopConnection(PopClient popClient);

    private bool CheckForEndOfData(StringBuilder sb);

    public void Dispose();

    protected virtual void Dispose(bool disposing);

    public string ReadMultiLineResponseString();

    public int ReadResponse(out byte[] bytes);

    public string ReadResponseString();

    private string SendCommandInternal(string command);

    public string SendDele(int messageId);

    public string SendList();

    public string SendList(int messageId);

    public string SendPass(string pass);

    public string SendQuit();

    public string SendRetr(int messageId);

    public string SendStat();

    public string SendUidl();

    public string SendUidl(int messageId);

    public string SendUser(string user);
}

Here's a partial list of the SendXXX-method implementations.

private string SendCommandInternal(string command)
{
    byte[] bytes = Encoding.UTF8.GetBytes(command);
    stream.Write(bytes, 0, bytes.Length);
    return command;
}

public string SendQuit()
{
    return SendCommandInternal("QUIT\r\n");
}

public string SendStat()
{
    return SendCommandInternal("STAT\r\n");
}

public string SendList(int messageId)
{
    return SendCommandInternal(String.Format("LIST {0}\r\n", messageId));
}

public string SendDele(int messageId)
{
    return SendCommandInternal(String.Format("DELE {0}\r\n", messageId));
}

It's pretty straightforward socket code, specially since the POP3 protocol is quite uncomplicated. The receive methods are also quite straightforward.

public string ReadResponseString()
{
    byte[] bytes;
    int count = this.ReadResponse(out bytes);
    return bytes.GetString(count);
}

public string ReadMultiLineResponseString()
{
    StringBuilder sb = new StringBuilder();

    byte[] bytes;

    do
    {
        int count = this.ReadResponse(out bytes);
        sb.Append(bytes.GetString(count));                
    }
    while( !CheckForEndOfData(sb) );

    return sb.ToString();
}

private char[] endMarker = { '\r', '\n', '.', '\r', '\n' };

private bool CheckForEndOfData(StringBuilder sb)
{
    if (sb.Length < 5)
        return false;

    char[] compare = new char[5];
    sb.CopyTo(sb.Length - 5, compare, 0, 5);

    return (endMarker as IStructuralEquatable).Equals(
        compare, EqualityComparer<char>.Default);
}

Every POP3 command has an associated command object, and all command objects implement the IPopCommand interface.

internal interface IPopCommand
{
    event EventHandler<PopClientDirectionalLogEventArgs> PopClientLog;

    void Execute(params object[] arguments);

    bool IsMultiLineResponse { get; }
}

There is an abstract BasePopCommand class that implements some of the common stuff and makes it easy to implement command classes.

internal abstract class BasePopCommand : IPopCommand
{
    private EventHandler<PopClientDirectionalLogEventArgs> PopClientLog;

    public event EventHandler<PopClientDirectionalLogEventArgs> PopClientLog;

    public BasePopCommand(PopConnection popConnection);
    private void CheckForErrorResponse();
    public void Execute(params object[] arguments);
    private void Execute(object argument);
    protected abstract string ExecuteInternal(object argument);
    protected void OnPopClientLog(string line, bool isServerResponse);
    protected virtual void ParseInternal();

    public virtual bool IsMultiLineResponse { get; }
    protected string MultiLineResponse { get; private set; }
    protected PopConnection PopConnection { get; private set; }
    protected string Response { get; private set; }
}

Here are some of the more important method implementations.

public void Execute(params object[] arguments)
{
    this.Execute(arguments.FirstOrDefault());
}

private void Execute(object argument)
{
    this.OnPopClientLog(ExecuteInternal(argument), false);
    this.Response = this.PopConnection.ReadResponseString();
    this.OnPopClientLog(this.Response, true);
    this.CheckForErrorResponse();
    if (this.IsMultiLineResponse)
    {
        this.MultiLineResponse = 
          this.PopConnection.ReadMultiLineResponseString();
    }

    this.ParseInternal();
}

protected virtual void ParseInternal()
{            
}

private void CheckForErrorResponse()
{
    if (this.Response.StartsWith("-ERR"))
    {
        throw new PopClientException(
          new String(this.Response.Skip(4).ToArray()).Trim());
    }
}

Derived classes now just need to implement ExecuteInternal and optionally ParseInternal (if they need to parse the response stream). Here's how the User command is implemented, it's one of the more simple ones as it does not do custom parsing on the response.

internal class UserPopCommand : BasePopCommand
{
    public UserPopCommand(PopConnection popConnection)
        : base(popConnection)
    {
    }

    protected override string ExecuteInternal(object argument)
    {
        return PopConnection.SendUser(argument as string);
    }
}

Here's a slightly more involved derived class that implements the Stat command.

internal class StatPopCommand : BasePopCommand
{
    public StatPopCommand(PopConnection popConnection)
        : base(popConnection)
    {
    }

    protected override string ExecuteInternal(object argument)
    {
        return PopConnection.SendStat();
    }

    private int count;

    public int Count
    {
        get { return count; }
    }

    private int size;

    public int Size
    {
        get { return size; }
    }

    protected override void ParseInternal()
    {
        string[] parts = this.Response.Trim().Split();

        if (parts.Length != 3 || !Int32.TryParse(parts[1], out count) 
          || !Int32.TryParse(parts[2], out size))
        {
            throw new PopClientException("Unknown STAT response from server.");
        }
    }
}

One of the most important commands is the Retr command, and here's how that's been implemented.

internal class RetrPopCommand : BasePopCommand
{
  public MailMessage Message { get; private set; }

  public DateTime ReceivedTime  { get; private set; }

  public RetrPopCommand(PopConnection popConnection)
      : base(popConnection)
  {
  }

  protected override string ExecuteInternal(object argument)
  {
      return PopConnection.SendRetr((int)argument);
  }

  protected override void ParseInternal()
  {
      var converter = new CDOMessageConverter(this.MultiLineResponse);
      this.Message = converter.ToMailMessage();
      this.ReceivedTime = converter.ReceivedTime;
  }

  public override bool IsMultiLineResponse
  {
      get
      {
          return true;
      }
  }
}

Notice the use of the CDOMessageConverter class. CDO (Collaboration Data Objects) is a COM component that's been part of Windows OSes since Windows 2000, and it has built in functionality to parse MIME based email (including full support for attachments). CDO has no idea about the

MailMessage

class, so I wrote a converter that will take a MIME string, construct a CDO message from it, and then convert the CDO message into a

MailMessage

object. It's fairly straightforward COM-interop, so I won't go into the details. The two classes do not have a one-to-one structural equivalence, so I had to make certain compromises, but as long as I was able to obtain all fields required to read an email message with attachments, I was not too concerned about superficial differences between the types.

The PopChat class provides a single point interface from where the PopClient class can invoke POP commands. Here's a snipped code listing that shows what the class does. In addition to exposing properties for each command, it also makes sure that all commands have their log events subscribed to via a common event handler.

internal class PopChat : IDisposable
{
  //...
  
  internal NothingPopCommand Nothing { get; private set; }
  internal UserPopCommand User { get; private set; }
  internal PassPopCommand Pass { get; private set; }
  internal StatPopCommand Stat { get; private set; }
  //...

  public PopChat(PopClient client)
  {
      //...

      new IPopCommand[] 
      { 
          Nothing = new NothingPopCommand(popConnection),
          User = new UserPopCommand(popConnection),
          Pass = new PassPopCommand(popConnection),
          Stat = new StatPopCommand(popConnection),
          Retr = new RetrPopCommand(popConnection),
          Quit = new QuitPopCommand(popConnection),
          List = new ListPopCommand(popConnection),
          Uidl = new UidlPopCommand(popConnection),
          Dele = new DelePopCommand(popConnection),
          ListAll = new ListAllPopCommand(popConnection),
          UidlAll = new UidlAllPopCommand(popConnection)
      }.ToList().ForEach(pc => pc.PopClientLog += PopCommand_PopClientLog);
  }

  private void PopCommand_PopClientLog(
    object sender, PopClientDirectionalLogEventArgs e)
  {
      this.client.LogLine(e.Line, e.IsServerResponse);   
  }
}

And finally, the actual POP chat is invoked from the BackgroundWorker thread that's used by the PopClient class.

private void Worker_DoWork(object sender, DoWorkEventArgs e)
{
    using (PopChat chat = new PopChat(this))
    {
        chat.Nothing.Execute();
        chat.User.Execute(this.Username);
        chat.Pass.Execute(this.Password);
        chat.Stat.Execute();
        chat.ListAll.Execute();
        chat.UidlAll.Execute();

        int count = chat.Stat.Count;
        int size = chat.Stat.Size;

        if (this.UidlsToIgnore.Count > 0)
        {
            var skipList = chat.UidlAll.Uidls.Values.Intersect(this.UidlsToIgnore);

            count -= skipList.Count();

            foreach (var uidl in skipList)
            {
                size -= chat.ListAll.MessageSizes[chat.UidlAll.Indices[uidl]];
            }
        }

        this.OnMailPopInfoFetched(count, size);

        for (int fetchIndex = 1; fetchIndex <= chat.Stat.Count; fetchIndex++)
        {
            if (worker.CancellationPending)
            {
                e.Cancel = true;
                break;
            }

            if (!this.UidlsToIgnore.Contains(chat.UidlAll.Uidls[fetchIndex]))
            {
                chat.Retr.Execute(fetchIndex);
                this.OnMailPopped(fetchIndex, chat.Retr.Message, 
                  chat.ListAll.MessageSizes[fetchIndex], 
                  chat.UidlAll.Uidls[fetchIndex], chat.Retr.ReceivedTime);

                if (this.DeleteMailAfterPop)
                {
                    chat.Dele.Execute(fetchIndex);
                }
            }
        }

        chat.Quit.Execute();
    }
}

Conclusion

If you run into specific issues with a POP server, the chat log (easily accessible via the event handlers) should tell you exactly what's going on. As always, feedback and criticism is welcome, and please feel free to post your comments through the discussion forum for this article. Although if you post something nasty or vote anything less than a 5, I have a Yaqui curse that I recently learned all ready to apply on you! *grin*

History

• November 8th, 2010 - Article first published.
• November 19th, 2010
  • Default POP port was incorrectly set to the SMTP port. This is now fixed.
  • Added support for skippable UIDLs. This lets you only retrieve mail that was not fetched earlier.
  • New command objects added for UIDL and LIST that supplement the existing versions, except that these do an index-less full fetch.