Chilkat.EmailBundle Class Overview

Chilkat.EmailBundle is a container for multiple Chilkat.Email objects. It is used to hold, retrieve, search, sort, remove, serialize, and reload groups of email messages. An email bundle is commonly returned by mail-related operations and can also be built manually by adding individual email objects.

What the Class Is Used For

Use Chilkat.EmailBundle when an application needs to work with a collection of email messages as a single object. The bundle can be sorted by date, sender, recipient, or subject; searched for a matching email; saved to XML; loaded from XML; or modified by adding and removing messages.

Hold Multiple Emails Store a group of Email objects and inspect the count with MessageCount.
Access by Index Retrieve the Nth email with EmailAt. Indexing begins at 0.
Search the Bundle Use FindEmail with JSON criteria to return the first matching email.
Persist as XML Save the bundle to XML or load a bundle from an XML file or XML string.

Typical Workflow

  1. Obtain an EmailBundle from a Chilkat mail operation, or create one and add emails with AddEmail.
  2. Check MessageCount to determine how many emails are in the bundle.
  3. Loop from 0 to MessageCount - 1 and call EmailAt to access each email.
  4. Optionally sort the bundle with SortByDate, SortBySender, SortByRecipient, or SortBySubject.
  5. Optionally search for a specific message with FindEmail.
  6. Save the bundle with SaveXml or get the XML text with GetXml.
  7. Check LastErrorText after failures or unexpected behavior.

Core Concepts

Concept Meaning Important Members
Email Collection A bundle is a collection of Email objects. MessageCount, AddEmail, EmailAt
Zero-Based Indexing The first email in the bundle is at index 0. EmailAt, RemoveEmailByIndex
Search by Criteria A matching email can be found using criteria supplied in a JsonObject. FindEmail
Sorting Emails can be sorted by common fields such as date, sender, recipient, or subject. SortByDate, SortBySender, SortByRecipient, SortBySubject
XML Serialization The bundle can be converted to XML and later loaded again. GetXml, SaveXml, LoadXml, LoadXmlString
Local Bundle Only Removing an email from the bundle modifies the local bundle object only. RemoveEmail, RemoveEmailByIndex

Properties

Property Purpose Guidance
MessageCount Returns the number of emails contained in the bundle. Use this when iterating through the bundle with EmailAt.
LastErrorText Provides 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.

Adding, Accessing, and Clearing Emails

Method Purpose Important Details
AddEmail Adds an Email object to the bundle. Use to build a bundle manually from individual email objects.
EmailAt Copies the Nth email in the bundle into a supplied Email object. Indexing begins at 0. Returns true for success and false for failure.
Clear Removes and discards all emails contained in the bundle object. Use when reusing the bundle object for a new set of emails.
Iteration pattern: Read MessageCount, then call EmailAt for each index from 0 through MessageCount - 1.

Searching the Bundle

Method Input Result
FindEmail Search criteria supplied in a JsonObject. Returns the first email in the bundle that matches the criteria and copies it into the supplied Email object.
Replacement note: FindEmail replaces the deprecated FindByHeader method. It currently provides the same functionality and is designed so additional search options can be added in the future.

Removing Emails

Method Removes Important Details
RemoveEmail A matching Email object from the bundle. This removes the email from the local bundle only. It does not remove the email from the mail server.
RemoveEmailByIndex The Nth email in the bundle. Indexing begins at 0.
Clear All emails in the bundle. Clears the bundle object entirely.
Server-side deletion: Removing an email from an EmailBundle does not delete the message from IMAP, POP3, or any mail server. It only modifies the local bundle.

Sorting Emails

Method Sorts By Argument
SortByDate Email date. Pass true for ascending order or false for descending order.
SortBySender Sender. Pass true for ascending order or false for descending order.
SortByRecipient Recipient. Pass true for ascending order or false for descending order.
SortBySubject Subject. Pass true for ascending order or false for descending order.

XML Persistence

Method Purpose Use When
GetXml Converts the bundle to an XML document in memory and returns it as a string. Use when the XML should be stored, inspected, transmitted, or processed in memory.
SaveXml Converts each email to XML and saves the bundle to an XML file. Use to persist an email bundle to disk for later reloading.
LoadXml Loads an email bundle from an XML file. Use to restore a bundle that was previously saved to an XML file.
LoadXmlString Loads an email bundle from an XML string. Use when the XML bundle data is already in memory.
Persistence workflow: Use SaveXml to persist a bundle to disk and LoadXml or LoadXmlString to recreate the bundle later.

Async Result Loading

Method Purpose Typical Use
LoadTaskResult Loads the email bundle from a completed asynchronous task. Use after an async mail operation completes and the result is an EmailBundle.

Method Summary by Category

Category Methods / Properties Purpose
Bundle contents MessageCount, AddEmail, EmailAt, Clear Count, add, retrieve, or clear emails in the bundle.
Search FindEmail Find the first email matching JSON-based search criteria.
Remove RemoveEmail, RemoveEmailByIndex Remove emails from the local bundle object.
Sort SortByDate, SortBySender, SortByRecipient, SortBySubject Sort the bundle by common email fields.
XML GetXml, SaveXml, LoadXml, LoadXmlString Serialize or reload a bundle as XML.
Async LoadTaskResult Load a bundle from a completed asynchronous task.
Diagnostics LastErrorText Read diagnostic information after failed or unexpected operations.

Diagnostics and Troubleshooting

Problem Area Member What to Check
No emails are available MessageCount Confirm the bundle was populated by a mail operation, XML load, async task, or calls to AddEmail.
Retrieving an email fails EmailAt Check that the index is within the range 0 to MessageCount - 1.
Search does not find the expected email FindEmail Verify the JSON search criteria and remember that the method returns the first matching email.
Email disappears from the bundle RemoveEmail, RemoveEmailByIndex, Clear Check whether the email was removed from the local bundle object. This does not imply deletion from the mail server.
Loaded XML does not produce the expected bundle LoadXml, LoadXmlString Confirm the XML was produced from an email bundle and that the input file or string is complete.
Async operation result is not available LoadTaskResult Confirm the asynchronous task completed successfully before loading the bundle result.
Need operation details after failure LastErrorText Check diagnostic text after failed or unexpected add, retrieve, search, remove, load, save, or async-result operations.

Common Pitfalls

Pitfall Better Approach
Using one-based indexing when retrieving emails. Use zero-based indexing. The first email is at 0.
Assuming RemoveEmail deletes the message from the mail server. Treat removal as a local bundle operation only. Use the appropriate mail class operation for server-side deletion.
Forgetting that FindEmail returns only the first match. Use iteration with EmailAt when all matching messages must be inspected.
Sorting the bundle before preserving the original order. Save or record any needed original order before calling a SortBy* method.
Reusing a bundle without clearing it. Call Clear before building a completely new bundle from scratch.
Ignoring diagnostic information after a failed operation. Check LastErrorText for details.

Best Practices

Recommendation Reason
Always check MessageCount before iterating. It prevents out-of-range access and makes loop boundaries clear.
Use EmailAt with a reusable Email object. The method copies the Nth email into the supplied object.
Use sorting methods before display or reporting. Sorting by date, sender, recipient, or subject makes bundles easier to inspect.
Use GetXml or SaveXml when the bundle must be preserved. XML serialization allows the bundle to be stored and reloaded later.
Use LoadTaskResult only after the async task is complete. It loads the bundle result from a completed asynchronous operation.
Distinguish local bundle changes from mail-server changes. Removing or clearing emails from the bundle does not delete messages from the server.
Check LastErrorText after failures. It provides useful diagnostic detail for bundle population, indexing, searching, XML persistence, removal, sorting, and async result loading.

Summary

Chilkat.EmailBundle is a simple but important collection class for working with multiple Email objects. It supports adding emails, retrieving emails by index, finding a matching email, sorting by common email fields, removing emails from the local bundle, clearing the bundle, saving to XML, loading from XML, and loading results from completed asynchronous tasks.

The most important practical guidance is to remember that indexing begins at 0, RemoveEmail only removes an email from the local bundle, FindEmail returns the first match, and LastErrorText should be checked whenever a method fails or behaves unexpectedly.