ImapEnvelopeDownloaded Event

Namespace: MailBee.ImapMail
Assembly: MailBee.NET (in MailBee.NET.dll) Version: 12.2.0 build 630 for .NET 4.5
public event ImapEnvelopeDownloadedEventHandler EnvelopeDownloaded


Type: MailBee.ImapMailImapEnvelopeDownloadedEventHandler

In the IMAP4 protocol, all message related information is returned as a series of FETCH responses (one response per each message). Each FETCH response may consist of various elements, and the most common of them is ENVELOPE. When processing the server response, MailBee parses every FETCH response into an Envelope object.

MailBee methods which download messages or envelopes raise EnvelopeDownloaded event is raised each time a FETCH response was parsed and corresponding Envelope object created. Currently, the list of methods which raise EnvelopeDownloaded and EnvelopeDataChunkReceived events is as follows:

Other methods never raise these events (even if deal with FETCH responses). For instance, GetFolderSize method gets FETCH responses containing the size of each message for all messages in the folder. Although this method does receive FETCH responses, it does not raise EnvelopeDownloaded and EnvelopeDataChunkReceived events.

The developer can use DownloadedEnvelope property to access the downloaded envelope. MessagePreview contains a reference to the MailMessage object within the envelope.

DownloadedEnvelope property is writable. For instance, the developer can set it to a null reference (Nothing in Visual Basic) to prevent this envelope from being added to the resulting collection. This can be used to filter incoming messages or to process messages directly in the event handler and avoid unnecessary memory overhead when the message is no longer needed.

Note Note
Sometimes, the mail server may send unilateral FETCH responses in addition to the requested ones. For instance, if the IMAP4 session lasts for a long period of time, and another client accesses the same folder simultaneously (for instance, downloads a message so it gets "\Seen" flag set), the server will also send unilateral FETCH response containing the updated flags of the amended message. Starting from MailBee.NET Objects v3.0, MailBee detects such unilateral responses and EnvelopeDownloaded event is NOT raised for them (MessageStatus event is raised instead). Also, MailBee takes unilateral responses into account for calculating the folder statistics (total number of messages, number of unseen messages, etc).
This console sample displays the total size (via GetFolderSize) and the individual sizes (via DownloadEnvelopes(String, Boolean, EnvelopeParts, Int32, String, String)) of all messages in the folder. The logging into a file is enabled. The sample demonstrates EnvelopeDownloaded is raised by DownloadEnvelopes(String, Boolean, EnvelopeParts, Int32, String, String) method only (despite the fact that both GetFolderSize and DownloadEnvelopes(String, Boolean, EnvelopeParts, Int32, String, String) calls make the server to produce the same FETCH responses, the log file shows this).
using System;
using MailBee;
using MailBee.ImapMail;

class Sample
    // EnvelopeDownloaded event handler.
    private static void OnEnvelopeDownloaded(object sender,
        ImapEnvelopeDownloadedEventArgs e)
        Console.WriteLine("Envelope (size and UID) of message #" +
            e.MessageNumber + " downloaded");

    // The actual code.
    static void Main(string[] args)
        Imap imp = new Imap();

        // Enable logging to demonstrate GetFolderSize() and
        // DownloadEnvelopes(Imap.AllMessages, EnvelopeParts.Rfc822Size, 0)
        // produce the same requests and responses.
        imp.Log.Filename = @"C:\Temp\log.txt";
        imp.Log.Enabled = true;

        // Subscribe to the EnvelopeDownloaded event.
        imp.EnvelopeDownloaded +=
            new ImapEnvelopeDownloadedEventHandler(OnEnvelopeDownloaded);

        // Connect to the server, login and select inbox.
        imp.Login("jdoe", "secret");

        // Get the total size of all messages in the folder, and display it.
        Console.WriteLine("The total size of all messages in Inbox is: " +
            imp.GetFolderSize() + " bytes");

        // Get the size of each message in the folder...
        EnvelopeCollection envs = imp.DownloadEnvelopes(Imap.AllMessages, false,
            EnvelopeParts.Rfc822Size, 0);

        // ... and display it.
        foreach (Envelope env in envs)
            Console.WriteLine("Size of message #" + env.MessageNumber + " is " +
                env.Size + " bytes");

See Also