RetrieveMailboxesEx Method

This method retrieves Mailboxes collection which contains mailboxes of the IMAP4 account. This collection includes only mailboxes which are passed user defined criteria.

Specail mailbox flags like \Trash or \Drafts are automatically available if the server supports SPECIAL-USE extension. If the server does not support SPECIAL-USE but supports XLIST, see example in GetCapabilities topic on how proceed with XLIST-way. Special mailbox flags will be available together with all other folder flags through Mailbox.Flags property of each Mailbox object in the returned collection.

Note: GMail does support both XLIST and SPECIAL-USE. It does not advertize SPECIAL-USE in its capability list but since SPECIAL-USE extension does not add new commands and all flags become automatically available, you don't need to check for extensions or do anything special to work with extra flags added by SPECIAL-USE.

Two flags ("\HasChildren" and "\HasNoChildren") are added by yet another extension, CHILDREN (supported by Gmail). They are ony useful in case if you work with very large number of mailboxes and don't want to load them all (OneLevelOnly option which gets a particular level of mailboxes without getting their children). These flags let the application understand which mailboxes in the received list have sub-mailboxes (for instance, the app can display '+' button near their names to let the user expand them).

objMailboxes = ObjectName.RetrieveMailboxes(RootMailBoxName, [SubscribedOnly], OneLevelOnly, [GetSpecialFoldersFlags])


Parameters:
RootMailboxName As String	(optional) If not empty only sub-mailboxes of the specified mailbox will be retrieved, otherwise all mailboxes of the account will be retrieved. Default is False meaning that no mailbox filter is set.
SubscribedOnly As Boolean	(optional) If True the only subscribed mailboxes will be retrieved (the parameter is ignored if GetSpecialFoldersFlags is True). Default is False
OneLevelOnly	(optional) If True only first level sub-folders of the mailbox will be retrieved. Default is False
GetSpecialFoldersFlags As Boolean	(optional) If True, MailBee will also determine special folder flags (Inbox/Drafts/Sent/Spam/Trash/etc) by using XLIST command instead of LIST (the server must support XLIST). Note that for the server which supports SPECIAL-USE extension, no special command needed and this parameter should be left False. XLIST is now considered deprecated. The default is False

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

Usage example:

' This sample gets first-level mailboxes list and selects last mailbox in the collection.
' Then, number of messages is displayed for this mailbox. 
Dim Mailer, Mailboxes
' 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.EnableLogging = True
Mailer.LogFilePath = "C:\Temp\imap4_log.txt"
Mailer.ClearLog
Mailer.LicenseKey = "put your license key"
If Mailer.Connect("mailserver.com", 143, "MyName", "MyPassword") Then
   Set Mailboxes = Mailer.RetrieveMailboxesEx("", False, True)
   If Not Mailboxes Is Nothing Then
      If (Mailboxes.Count > 0) Then
         If Mailer.SelectMailbox(Mailboxes(Mailboxes.Count).Name) Then
            MsgBox Mailer.MessageCount & " messages in " & Mailboxes(Mailboxes.Count).Name
         End If
      End If
   End If
   Mailer.Disconnect
End If