Occurs when a FETCH response is received from the IMAP4 server and the method which receives mail messages or envelopes (such as DownloadEnvelopes) is in progress.

Event Data

The event handler receives an argument of type ImapEnvelopeDownloadedEventArgs containing data related to this event. The following ImapEnvelopeDownloadedEventArgs properties provide information specific to this event.

Remarks

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:

• DownloadMessageHeaders
• DownloadEntireMessage
• DownloadEntireMessages
• DownloadEnvelopes
• BeginDownloadEnvelopes

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    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).

Example

This console sample displays the total size (via GetFolderSize) and the individual sizes (via DownloadEnvelopes) of all messages in the folder. The logging into a file is enabled. The sample demonstrates EnvelopeDownloaded is raised by DownloadEnvelopes method only (despite the fact that both GetFolderSize and DownloadEnvelopes calls make the server to produce the same FETCH responses, the log file shows this).

[C#]
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;
        imp.Log.Clear();

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

        // Connect to the server, login and select inbox.
        imp.Connect("mail.domain.com");
        imp.Login("jdoe", "secret");
        imp.SelectFolder("INBOX");

        // 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");
        }

        imp.Disconnect();
    }
}

[Visual Basic]
Imports System
Imports MailBee
Imports MailBee.ImapMail

Module Sample
    ' EnvelopeDownloaded event handler.
    Private Sub OnEnvelopeDownloaded(ByVal sender As Object, ByVal e As ImapEnvelopeDownloadedEventArgs)
        Console.WriteLine("Envelope (size and UID) of message #" & e.MessageNumber & " downloaded")
    End Sub

    ' The actual code.
    Sub Main(ByVal args As String())
        Dim imp As 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
        imp.Log.Clear()

        ' Subscribe to the EnvelopeDownloaded event.
        AddHandler imp.EnvelopeDownloaded, AddressOf OnEnvelopeDownloaded

        ' Connect to the server, login and select inbox.
        imp.Connect("mail.company.com")
        imp.Login("jdoe", "secret")
        imp.SelectFolder("INBOX")

        ' 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...
        Dim envs As EnvelopeCollection = imp.DownloadEnvelopes(Imap.AllMessages, _
            False, EnvelopeParts.Rfc822Size, 0)

        ' ... and display it.
        For Each env As Envelope In envs
            Console.WriteLine("Size of message #" & env.MessageNumber & _
                 " is " & env.Size & " bytes")
        Next

        imp.Disconnect()
    End Sub
End Module

See Also

Imap Class | MailBee.ImapMail Namespace | EnvelopeDataChunkReceived | DownloadMessageHeaders | DownloadEntireMessage | DownloadEntireMessages | DownloadEnvelopes

---