Chilkat.Mailboxes Class Overview

Chilkat.Mailboxes represents a collection of IMAP mailboxes returned by the Chilkat.Imap class. It provides indexed access to mailbox names and mailbox attributes such as flags, selectable status, marked status, and whether child mailboxes exist or may be created.

Important: Mailboxes Is an IMAP Helper Class

Chilkat.Mailboxes is intended for use with Chilkat.Imap. It is not a general-purpose mailbox manager and does not itself connect to an IMAP server, list folders, select folders, or retrieve email. Instead, it acts as a container returned by IMAP methods that list mailboxes, and it provides methods for inspecting the mailbox names and attributes in that returned collection.

Terminology note: Chilkat.Mailboxes contains mailbox names and mailbox flags. It does not contain email messages. For sets of IMAP message UIDs or sequence numbers, use Chilkat.MessageSet.
Used by Imap Holds mailbox collections returned by Chilkat.Imap methods.
Indexed Mailbox Access Retrieve mailbox names and flags by zero-based index.
Inspect Mailbox Attributes Check whether a mailbox is selectable, marked, or has inferiors.
Async Result Support Load a mailbox collection from a completed asynchronous task.

Typical Workflow

  1. Use a Chilkat.Imap method that returns a Mailboxes object.
  2. Check Count to determine how many mailboxes are in the collection.
  3. Iterate from index 0 through Count - 1.
  4. Use GetName to retrieve each mailbox name.
  5. Use GetFlags, GetNumFlags, or GetNthFlag to inspect mailbox flags.
  6. Use IsSelectable, IsMarked, HasInferiors, or HasFlag to check mailbox attributes.
  7. Use GetMailboxIndex when you need to locate a mailbox by name.
  8. Check LastErrorText if an operation fails or behaves unexpectedly.

Core Concepts

Concept Meaning Important Members
Mailbox Collection A list of mailbox names and attributes returned by an IMAP operation. Count, GetName, GetMailboxIndex
Mailbox Flags Attribute names associated with a mailbox, such as \HasNoChildren or \Important. GetFlags, GetNumFlags, GetNthFlag, HasFlag
Selectable Mailbox A mailbox that can be selected for IMAP operations. IsSelectable
Marked Mailbox A mailbox with the IMAP marked attribute. IsMarked
Inferiors Child mailboxes that exist now, or child mailboxes that may be created in the future. HasInferiors
Async Result Loading Loading a mailbox collection from a completed asynchronous IMAP task. LoadTaskResult

Properties

Property Purpose Guidance
Count Returns the number of mailboxes in the collection. Use before iterating by index. Valid indexes are 0 through Count - 1.
LastErrorText Diagnostic information for the last method or property access. Check after failures or unexpected behavior. Diagnostic information may be available regardless of success or failure.

Retrieving Mailbox Names

Method Purpose Important Details
GetName Returns the name of the Nth mailbox. Indexing begins at 0.
GetMailboxIndex Returns the index of the mailbox with the specified name. Use when you need to locate a mailbox by name before checking its flags or attributes.
Indexing rule: Mailbox indexes are zero-based. The first mailbox is at index 0.

Inspecting Mailbox Flags

Method Returns Use When
GetFlags A comma-separated list of flags for the Nth mailbox. Use when you want all flags in one string, such as \HasNoChildren,\Important.
GetNumFlags Number of flags for the Nth mailbox. Use before iterating flags with GetNthFlag. Returns -1 if the mailbox index is out of range.
GetNthFlag The Nth flag for the Mth mailbox. Use when processing flags individually.
HasFlag True if the Nth mailbox has the specified flag. The flag name is case-insensitive and should begin with a backslash, such as \Flagged.

Mailbox Attribute Helpers

Method Meaning Why It Matters
IsSelectable Returns true if the Nth mailbox is selectable. Selectable mailboxes can be selected for IMAP operations.
IsMarked Returns true if the Nth mailbox is marked. Use to check whether the mailbox has the IMAP marked attribute.
HasInferiors Returns true if the Nth mailbox has child mailboxes, or if child mailboxes may be created in the future. Use to understand mailbox hierarchy and whether the mailbox can contain children.
Inferiors note: \HasNoChildren should not be confused with the IMAP Noinferiors attribute. Noinferiors means no child mailboxes exist now and none can be created in the future.

Async Result Support

Method Purpose Use When
LoadTaskResult Loads the mailboxes object from a completed asynchronous task. Use after an async IMAP operation completes and the task result contains a mailbox collection.

Method Summary by Category

Category Methods / Properties Purpose
Inspect collection Count Get the number of mailboxes in the collection.
Mailbox names GetName, GetMailboxIndex Retrieve mailbox names by index or find the index for a named mailbox.
Mailbox flags GetFlags, GetNumFlags, GetNthFlag, HasFlag Read all flags, count flags, retrieve individual flags, or test for a specific flag.
Mailbox attributes IsSelectable, IsMarked, HasInferiors Check whether a mailbox is selectable, marked, or can have child mailboxes.
Async workflow LoadTaskResult Load the mailbox collection from a completed asynchronous task.
Diagnostics LastErrorText Read diagnostic information after failed or unexpected operations.

Diagnostics and Troubleshooting

Problem Area Member What to Check
Mailbox index is out of range Count, GetName, GetFlags, GetNumFlags Check Count before using an index. Valid indexes are 0 through Count - 1.
Flag lookup does not match HasFlag Make sure the flag begins with a backslash, such as \Flagged. The comparison is case-insensitive.
Need to process flags individually GetNumFlags, GetNthFlag Call GetNumFlags first, then iterate flag indexes for the mailbox.
Mailbox cannot be selected IsSelectable Check whether the mailbox is selectable before attempting IMAP operations that require selecting a mailbox.
Unexpected hierarchy behavior HasInferiors Remember that this indicates either existing child mailboxes or the possibility of creating child mailboxes in the future.
Async mailbox listing result is not available LoadTaskResult Confirm the asynchronous task completed and that its result is a mailboxes object.
Need operation details after failure LastErrorText Check diagnostic text after failed or unexpected mailbox collection operations.

Common Pitfalls

Pitfall Better Approach
Treating Mailboxes as a general-purpose collection. Use it specifically with Chilkat.Imap mailbox listing and mailbox inspection workflows.
Confusing mailboxes with messages. Mailboxes contains mailbox names and attributes. It does not contain email messages or message IDs.
Assuming indexes are 1-based. Indexing begins at 0.
Calling GetNthFlag without checking the number of flags. Use GetNumFlags first.
Passing a flag name without the leading backslash. Use flag names such as \Flagged, \HasNoChildren, or \Important.
Confusing \HasNoChildren with Noinferiors. Noinferiors means no child mailboxes exist now and none can be created in the future.
Ignoring diagnostics after unexpected behavior. Check LastErrorText for details.

Best Practices

Recommendation Reason
Use Mailboxes only with Chilkat.Imap mailbox workflows. The class exists to hold mailbox collections returned by IMAP operations.
Use Count before indexed access. It prevents out-of-range calls to methods such as GetName and GetFlags.
Use GetMailboxIndex when looking up a known mailbox name. It avoids manually scanning the collection.
Use IsSelectable before attempting to select a mailbox. Not every listed mailbox is necessarily selectable.
Use HasFlag for direct flag checks. It is simpler than parsing the comma-separated string returned by GetFlags.
Use GetNumFlags and GetNthFlag for structured flag iteration. It avoids manual parsing of comma-separated flag text.
Check LastErrorText after failures. It provides useful diagnostic detail for failed or unexpected mailbox collection operations.

Summary

Chilkat.Mailboxes is an IMAP-specific helper class used by Chilkat.Imap to return and inspect collections of mailboxes. It provides the mailbox count, mailbox names, mailbox indexes, flags, selectable status, marked status, and information about whether a mailbox has or may have child mailboxes.

The most important practical guidance is to treat this class as an IMAP mailbox collection, not a message collection; use Count before indexed access; remember indexes are zero-based; use HasFlag, IsSelectable, and HasInferiors to inspect mailbox attributes; and check LastErrorText whenever an operation fails or behaves unexpectedly.