ImapDownloadEnvelopesEx Method
Fetches message envelopes, bodies, headers, flags, attributes, etc from the server allowing you to request different items for every message in the list.

Namespace: MailBee.ImapMail
Assembly: MailBee.NET (in MailBee.NET.dll) Version: 11.2.0 build 590 for .NET 4.5
Syntax
public EnvelopeCollection DownloadEnvelopesEx(
	long[] messageIndices,
	bool indicesAreUids,
	EnvelopeParts[] parts,
	int[] bodyPreviewSizes,
	string[][] extraHeaders,
	string[][] extraItems
)

Parameters

messageIndices
Type: SystemInt64
The array of UIDs or message numbers of the messages to be fetched.
indicesAreUids
Type: SystemBoolean
If true, messageIndices holds UIDs; otherwise, ordinal message numbers.
parts
Type: MailBee.ImapMailEnvelopeParts
For every message to be fetched, denotes its EnvelopeParts to be requested. If a null reference (Nothing in Visual Basic), MailBee will use Uid for all messages.
bodyPreviewSizes
Type: SystemInt32
For every message to be fetched, denotes how many bytes of the raw body part to download in addition to the raw header part. If a null reference, MailBee will use 0 for all messages.
extraHeaders
Type: SystemString
For every message to be fetched, denotes its extra MIME headers to be requested. If a null reference MailBee will not request any additional headers for any messages.
extraItems
Type: SystemString
For every message to be fetched, denotes its extra items to be requested. If a null reference MailBee will not request any additional items for any messages.

Return Value

Type: EnvelopeCollection
EnvelopeCollection object if message envelopes were downloaded successfully; otherwise, a null reference (Nothing in Visual Basic).
Exceptions
ExceptionCondition
MailBeeInvalidArgumentExceptionmessageIndices is a null reference (Nothing in Visual Basic) or empty; bodyPreviewSizes, extraHeaders and extraItems have length different from messageIndices length.
MailBeeExceptionAn error occurred and ThrowExceptions is true.
Remarks

Use this method if you want to download different elements for different messages and would like to have the entire operation complete as a single command (pipelined batch). Typical cases for that are downloading text bodies or certain types of attachments from multiple messages. For other cases (when you need the same items for all messages, like envelope, header, full message, etc), use DownloadEnvelopes(String, Boolean, EnvelopeParts, Int32, String, String) method or its overloads.

The main advantage of DownloadEnvelopesEx(Int64, Boolean, EnvelopeParts, Int32, String, String) method is speed. You can do the same calling DownloadEnvelopes(String, Boolean, EnvelopeParts, Int32, String, String) multiple times (one call per message) each time requesting different message items. DownloadEnvelopesEx(Int64, Boolean, EnvelopeParts, Int32, String, String) just makes it possible to send all the requests at once and thus save time on multiple round-trips FETCH requests to the server and FETCH responses back from it. If performance is not a concern, use DownloadEnvelopes(String, Boolean, EnvelopeParts, Int32, String, String). See GetEnvelopeItem(String, Boolean) for example.

Usually, DownloadEnvelopesEx(Int64, Boolean, EnvelopeParts, Int32, String, String) method is used after DownloadEnvelopes(String, Boolean, EnvelopeParts, Int32, String, String) which requested body structures of the messages. Then you code analyzes these body structures, composes FETCH requests and the expected items in FETCH responses, and supplies the collected information to DownloadEnvelopesEx(Int64, Boolean, EnvelopeParts, Int32, String, String) method.

Examples
Two samples in this topic (you may also find the sample in BeginDownloadEnvelopesEx(Int64, Boolean, EnvelopeParts, Int32, String, String, AsyncCallback, Object) topic). The first sample downloads all images from all e-mails in inbox (not downloading anything else) and saves them to disk.
using System;
using System.Collections;
using MailBee;
using MailBee.ImapMail;
using MailBee.Mime;

class Sample
{
    static void Main(string[] args)
    {
        Imap imp = new Imap();

        // Enable logging for troubleshooting (for instance, you can see
        // if you send and receive correct FETCH requests and responses.
        imp.Log.Filename = @"C:\Temp\log.txt";
        imp.Log.Enabled = true;
        imp.Log.Clear();

        // Connect to the server, login and select inbox.
        imp.Connect("mail.company.com");
        imp.Login("user", "password");
        imp.SelectFolder("INBOX");

        // Download body structure for all e-mails in the inbox.
        EnvelopeCollection envs = imp.DownloadEnvelopes(Imap.AllMessages, true,
            EnvelopeParts.BodyStructure, 0);

        // The array of lists of FETCH keys to request from the server.
        string[][] fetchRequestKeyListArray = new string[envs.Count][];

        // The array of lists of FETCH keys to expect from the server in return
        // to requests of items listed in each element of fetchRequestKeyListArray.
        string[][] fetchResponseKeyListArray = new string[envs.Count][];

        // UIDs of the messages for which we received the body structure.
        long[] uids = new long[envs.Count];

        for (int i = 0; i < envs.Count; i++)
        {
            Envelope env = envs[i];

            ArrayList fetchRequestKeyList = new ArrayList();
            ArrayList fetchResponseKeyList = new ArrayList();

            // Get body structures of all MIME parts as flat list.
            ImapBodyStructureCollection parts = env.BodyStructure.GetAllParts();
            foreach (ImapBodyStructure part in parts)
            {
                if (part.ContentType.ToLower().IndexOf("image/") > -1)
                {
                    if (parts.Count > 1)
                    {
                        // For each image, we request its MIME part header and body
                        // (the IMAP4 protocol does not support getting the entire MIME
                        // part as a single block of data). Also note using .MIME instead of .HEADER
                        // because some mail servers don't support .HEADER syntax.
                        fetchRequestKeyList.Add("BODY.PEEK[" + part.PartID + ".MIME]");
                        fetchRequestKeyList.Add("BODY.PEEK[" + part.PartID + "]");

                        // For BODY.PEEK[...] request the server will return BODY[...] response.
                        fetchResponseKeyList.Add("BODY[" + part.PartID + ".MIME]");
                        fetchResponseKeyList.Add("BODY[" + part.PartID + "]");
                    }
                    else
                    {
                        fetchRequestKeyList.Add("BODY.PEEK[HEADER]");
                        fetchRequestKeyList.Add("BODY.PEEK[TEXT]");

                        // For BODY.PEEK[...] request the server will return BODY[...] response.
                        fetchResponseKeyList.Add("BODY[HEADER]");
                        fetchResponseKeyList.Add("BODY[TEXT]");
                    }
                }
            }

            // Second time, we'll get message by its UID. This will avoid the situation
            // when new message arrives between two queries (and thus it could be possible
            // to download wrong message second time).
            uids[i] = env.Uid;

            // Save the generated items for FETCH request and FETCH response.
            fetchRequestKeyListArray[i] = (string[])fetchRequestKeyList.ToArray(typeof(string));
            fetchResponseKeyListArray[i] = (string[])fetchResponseKeyList.ToArray(typeof(string));
        }

        if (envs.Count > 0)
        {
            // Download images.
            envs = imp.DownloadEnvelopesEx(uids, true,
                null, null, null,
                fetchRequestKeyListArray);

            foreach (Envelope env in envs)
            {
                // We need this to find FETCH request and response keys
                // which correspond to the envelope being examined.
                int index = Array.IndexOf(uids, env.Uid);

                if (index < 0)
                {
                    // For some odd reason, we got envelope we haven't requested.
                    // Hope this will never happen. Anyway, skip such envelope.
                    continue;
                }

                string[] fetchRequestKeys = fetchRequestKeyListArray[index];
                string[] fetchResponseKeys = fetchResponseKeyListArray[index];

                for (int i = 0; i < fetchRequestKeys.Length; i += 2)
                {
                    // Get MIME part header data.
                    byte[] mimePartHeader = (byte[])env.GetEnvelopeItem(
                        fetchResponseKeys[i], true);

                    // Get MIME part body data.
                    byte[] mimePartBody = (byte[])env.GetEnvelopeItem(
                        fetchResponseKeys[i + 1], true);

                    // Build MIME part data from header data and body data.
                    byte[] mimePartData = new byte[mimePartHeader.Length + mimePartBody.Length];
                    Buffer.BlockCopy(mimePartHeader, 0, mimePartData, 0, mimePartHeader.Length);
                    Buffer.BlockCopy(mimePartBody, 0, mimePartData,
                        mimePartHeader.Length, mimePartBody.Length);
                    mimePartHeader = null;
                    mimePartBody = null;

                    // Build Attachment object from the MIME part data.
                    MimePart part = MimePart.Parse(mimePartData);
                    Attachment picture = new Attachment(part);

                    // Save the image into C:\Temp folder.
                    picture.SaveToFolder(@"C:\Temp", false);
                }
            }
        }

        imp.Disconnect();
    }
}

The second example is very similar to the first one but it downloads HTML and plain-text bodies rather than images.
using System;
using System.Collections;
using MailBee;
using MailBee.ImapMail;
using MailBee.Mime;

class Sample
{
    static void Main(string[] args)
    {
        Imap imp = new Imap();

        // Enable logging for troubleshooting (for instance, you can see
        // if you send and receive correct FETCH requests and responses.
        imp.Log.Filename = @"C:\Temp\log.txt";
        imp.Log.Enabled = true;
        imp.Log.Clear();

        // Connect to the server, login and select inbox.
        imp.Connect("mail.company.com");
        imp.Login("user", "password");
        imp.SelectFolder("INBOX");

        // Download body structure for all e-mails in the inbox.
        EnvelopeCollection envs = imp.DownloadEnvelopes(Imap.AllMessages, true,
            EnvelopeParts.BodyStructure, 0);

        // The array of lists of FETCH keys to request from the server.
        string[][] fetchRequestKeyListArray = new string[envs.Count][];

        // The array of lists of FETCH keys to expect from the server in return
        // to requests of items listed in each element of fetchRequestKeyListArray.
        string[][] fetchResponseKeyListArray = new string[envs.Count][];

        // UIDs of the messages for which we received the body structure.
        long[] uids = new long[envs.Count];

        for (int i = 0; i < envs.Count; i++)
        {
            Envelope env = envs[i];

            ArrayList fetchRequestKeyList = new ArrayList();
            ArrayList fetchResponseKeyList = new ArrayList();

            // Get body structures of all MIME parts as flat list.
            ImapBodyStructureCollection parts = env.BodyStructure.GetAllParts();
            foreach (ImapBodyStructure part in parts)
            {
                string contentType = part.ContentType.ToLower();
                string disposition = (part.Disposition == null ? string.Empty : part.Disposition.ToLower());
                if (disposition != "attachment" &&
                    (contentType == "text/plain" || contentType == "text/html"))
                {
                    if (parts.Count > 1)
                    {
                        // For each text body part, we request its MIME part header and body
                        // (the IMAP4 protocol does not support getting the entire MIME
                        // part as a single block of data). Also note using .MIME instead of .HEADER
                        // because some mail servers don't support .HEADER syntax.
                        fetchRequestKeyList.Add("BODY.PEEK[" + part.PartID + ".MIME]");
                        fetchRequestKeyList.Add("BODY.PEEK[" + part.PartID + "]");

                        // For BODY.PEEK[...] request the server will return BODY[...] response.
                        fetchResponseKeyList.Add("BODY[" + part.PartID + ".MIME]");
                        fetchResponseKeyList.Add("BODY[" + part.PartID + "]");
                    }
                    else
                    {
                        fetchRequestKeyList.Add("BODY.PEEK[HEADER]");
                        fetchRequestKeyList.Add("BODY.PEEK[TEXT]");

                        // For BODY.PEEK[...] request the server will return BODY[...] response.
                        fetchResponseKeyList.Add("BODY[HEADER]");
                        fetchResponseKeyList.Add("BODY[TEXT]");
                    }
                }
            }

            // Second time, we'll get message by its UID. This will avoid the situation
            // when new message arrives between two queries (and thus it could be possible
            // to download wrong message second time).
            uids[i] = env.Uid;

            // Save the generated items for FETCH request and FETCH response.
            fetchRequestKeyListArray[i] = (string[])fetchRequestKeyList.ToArray(typeof(string));
            fetchResponseKeyListArray[i] = (string[])fetchResponseKeyList.ToArray(typeof(string));
        }

        if (envs.Count > 0)
        {
            // Download text parts.
            envs = imp.DownloadEnvelopesEx(uids, true, null, null, null, fetchRequestKeyListArray);

            foreach (Envelope env in envs)
            {
                // We need this to find FETCH request and response keys
                // which correspond to the envelope being examined.
                int index = Array.IndexOf(uids, env.Uid);

                if (index < 0)
                {
                    // For some odd reason, we got envelope we haven't requested.
                    // Hope this will never happen. Anyway, skip such envelope.
                    continue;
                }

                string[] fetchRequestKeys = fetchRequestKeyListArray[index];
                string[] fetchResponseKeys = fetchResponseKeyListArray[index];

                for (int i = 0; i < fetchRequestKeys.Length; i += 2)
                {
                    // Get MIME part header data.
                    byte[] mimePartHeader = (byte[])env.GetEnvelopeItem(
                        fetchResponseKeys[i], true);

                    // Get MIME part body data.
                    byte[] mimePartBody = (byte[])env.GetEnvelopeItem(
                        fetchResponseKeys[i + 1], true);

                    // Build MIME part data from header data and body data.
                    byte[] mimePartData = new byte[mimePartHeader.Length + mimePartBody.Length];
                    Buffer.BlockCopy(mimePartHeader, 0, mimePartData, 0, mimePartHeader.Length);
                    Buffer.BlockCopy(mimePartBody, 0, mimePartData,
                        mimePartHeader.Length, mimePartBody.Length);
                    mimePartHeader = null;
                    mimePartBody = null;

                    // Build TextBodyPart object from the MIME part data.
                    MimePart part = MimePart.Parse(mimePartData);
                    TextBodyPart textPart = new TextBodyPart(part);

                    // Print content-type and text content of the message.
                    Console.WriteLine("For message with UID=" + env.Uid);
                    Console.WriteLine("Content-Type=" + part.ContentType);
                    Console.WriteLine("The text follows...");
                    Console.WriteLine(textPart.Text);
                    Console.WriteLine("---------------------------------");
                    Console.WriteLine();
                }
            }
        }

        imp.Disconnect();
    }
}
See Also