RetrieveEnvelopesEx Method

Retrieves one or more message envelopes (and, optionally, extended information such as body structure and message preview) from currently selected IMAP4 mailbox.

To retrieve single message envelope only, specify the same value for the First and the Last parameters.

To get an arbitrary set of messages, specify MessageSet property and pass -1 as First value (Last value is not important when First is -1). AsUID parameter is still honored when IDs are taken from MessageSet property (depending on AsUID value, they will be treated as UIDs or ordinal message numbers).

If your IMAP server returns broken envelope (which can't be parsed by MailBee) among with good ones and you still want to continue receiving the data in such cases, you may set IgnoreFailures parameter to True to force ignoring broken envelopes. In such case, this method returns all parsed envelopes collection (i.e. not Nothing value), but ErrCode and IsError properties show that an error occurred (connection with the IMAP server will be lost). This allows you to get all envelopes retrieved prior to the error occurred. If IgnoreFailures is False, the method returns Nothing on any failure.

Note: For optimal performance, it's not recommended to retrieve large number (hundreds or thousands) of envelopes with extended information (such as large message preview) at once. Because envelopes are usually used for preview purposes such as building message list, downloading too much data may seriously increase response time of the end system.

objEnvelopes = ObjectName.RetrieveEnvelopesEx(First, Last, AsUID, [AlsoGetBodyStructure], [AlsoGetMessagePreview], [BodyPreviewSize], [IgnoreFailures])


Parameters:
First As Long	Message number or UID of the first message envelope to retrieve, or -1 to use MessageSet as input.
Last As Long	Message number or UID of the last message envelope to retrieve, or -1 to denote the last message in the mailbox.
AsUID As Boolean	If True, First and Last parameters must be specified as UIDs (unique-IDs). Otherwise, First and Last must be message numbers.
AlsoGetBodyStructure As Boolean	(optional) If True, BodyStructure property of each Envelope object in returned collection contains body structure of the message. If False, BodyStructure is Nothing. Default is False.
AlsoGetMessagePreview As Boolean	(optional) If True, MessagePreview property of each Envelope object in returned collection contains the message preview. If False, MessagePreview is Nothing. Default is False.
BodyPreviewSize As Long	(optional) Specifies the number of bytes of the message body to be returned in addition to message headers for MessagePreview. If AlsoGetMessagePreview=False, BodyPreviewSize makes no sense. If BodyPreviewSize=-1, the entire message gets downloaded but \Seen flag is not set (-2 gets the entire message with \Seen flag set). Default is 0.
IgnoreFailures As Boolean	(optional) If True, forces the method to ignore broken envelopes and parse all other ones which can be parsed. Default is False.

Return value As MailBee.Envelopes	On success, Envelopes collection is returned. On failure, return value is Nothing

Usage example:

' This sample displays preview of body text (taken from first
' 1000 bytes of the body) of every message in Inbox. Broken envelopes
' don't cause the method to fail.
Dim Mailer, Envelopes, Envelope
'Using visual basic to create object
Set Mailer = CreateObject("MailBee.IMAP4")
'Using ASP to create object
'Set Mailer = Server.CreateObject("MailBee.IMAP4")
'In ASP use Response.Write instead of MsgBox
Mailer.LicenseKey = "put your license key here"
If Mailer.Connect("mailserver.com", 143, "MyName", "MyPassword") Then
  If Mailer.SelectMailbox("Inbox") Then
    Set Envelopes = Mailer.RetrieveEnvelopesEx _
      (1, -1, False, False, True, 1000, True)
    If Not Envelopes Is Nothing Then
      For Each Envelope In Envelopes
        MsgBox Envelope.MessagePreview.BodyText
      Next
    End If
  End If
  Mailer.Disconnect
End If