---
product: Chilkat
product_version: 11.7.0
language: pascal
language_label: Lazarus Pascal
class: EmailBundle
license: bundle
deprecated: false
reference_html: https://www.chilkatsoft.com/refdoc/pascal_EmailBundleRef.html
---
# Chilkat EmailBundle — Lazarus Pascal — v11.7.0

> Chilkat 11.7.0 · language=pascal · class=EmailBundle
> Other versions: replace `11.7.0` in this URL. Other languages: `https://www.chilkatsoft.com/ai-docs/v/11.7.0/<lang>/classes/EmailBundle.md`.
> Language-wide rules (install, unlock, error model, strings/bytes): `https://www.chilkatsoft.com/ai-docs/v/11.7.0/pascal/guide.md`.

## Purpose

EmailBundle

**Hold, search, sort, remove, save, and reload groups of email messages.**

`EmailBundle` is a container for multiple `Email` objects. It is commonly returned by mail-related operations and can also be built manually by adding individual email messages. The class provides a simple way to work with groups of messages: retrieve emails by index, search for a matching email, sort by common email fields, remove messages, clear the bundle, and serialize or reload the collection as XML.

**Email collection**

Store multiple `Email` objects together after receiving, loading, filtering, or manually building a message set.

**Retrieve messages**

Use the message count and indexed access methods to retrieve individual emails for inspection, processing, saving, or sending.

**Search within the bundle**

Locate a specific email in the collection when application logic needs to find a matching message.

**Sort messages**

Sort the bundle by date, sender, recipient, or subject to organize messages before processing or display.

**Remove or clear emails**

Remove individual messages by object or index, or clear the entire bundle when the collection is no longer needed.

**Save and reload**

Serialize the bundle to XML and reload it later, or load task results that return an email bundle.

**Common pattern:** Receive or build a bundle of `Email` objects, loop from `0` to `MessageCount - 1`, retrieve each message with `EmailAt`, and then inspect, save, sort, remove, or process each email as needed. Use `EmailBundle` for the group and `Email` for the individual message contents.

For an extended overview, see [EmailBundle Class Overview](https://www.chilkatsoft.com/emailbundle_class_overview.asp).

## Object creation, unlocking and error handling

**Create / Free**

```pascal
uses
  Chilkat.EmailBundle;

var
  obj: TEmailBundle;
begin
  obj := TEmailBundle.Create;
  try
    if not obj.IsValid then
      raise Exception.Create('Failed to create a TEmailBundle instance.');

    // ... use obj ...

  finally
    obj.Free;
  end;
end;
```

`constructor Create;`

Allocates the underlying CkEmailBundle object and returns a new TEmailBundle instance. Simply adding **Chilkat.EmailBundle** to the unit's `uses` clause is enough to locate and bind to the Chilkat shared library (DLL / .so / .dylib) at runtime — no separate load step is required. Check `obj.IsValid` after calling `Create`; it is `False` if the underlying library could not be found/loaded or the object could not be allocated (for example, when unlicensed).

`destructor Destroy; override;`

Every TEmailBundle created by calling `Create` should eventually be released by calling `.Free` (inherited from `TObject`). The destructor automatically disposes the underlying CkEmailBundle handle. A native (unmanaged) memory leak occurs if the object is never freed.

Call `Global.UnlockBundle` once at the start of the program, before using this or any other Chilkat class. Any string unlocks a fully functional 30-day trial; a purchased unlock code is used in production. See `guide.md` for the exact code in Lazarus Pascal.

## Members common to every Chilkat class

Documented once per language in `common-members.md`; listed here so this page is self-contained.

| Property | Signature | Access | Meaning |
|---|---|---|---|
| `DebugLogFilePath` | `property DebugLogFilePath: string read GetDebugLogFilePath write SetDebugLogFilePath;` | read/write | If set to a file path, this property logs the LastErrorText of each Chilkat method or property call to the specified file. |
| `LastErrorHtml` | `property LastErrorHtml: string read GetLastErrorHtml;` | read-only | Provides HTML-formatted information about the last called method or property. |
| `LastErrorText` | `property LastErrorText: string read GetLastErrorText;` | read-only | Provides plain text information about the last called method or property. |
| `LastErrorXml` | `property LastErrorXml: string read GetLastErrorXml;` | read-only | Provides XML-formatted information about the last called method or property. |
| `LastMethodSuccess` | `property LastMethodSuccess: Boolean read GetLastMethodSuccess write SetLastMethodSuccess;` | read/write | Indicates the success or failure of the most recent method call: `True` means success, `False` means failure. |
| `VerboseLogging` | `property VerboseLogging: Boolean read GetVerboseLogging write SetVerboseLogging;` | read/write | If set to `True`, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. |
| `Version` | `property Version: string read GetVersion;` | read-only | Version of the component/library, such as "10.1.0" |

## Member index

| Member | Kind | Signature |
|---|---|---|
| `MessageCount` | property, read-only | `property MessageCount: Integer read GetMessageCount;` |
| `AddEmail` | method | `// email is a TEmail object. function AddEmail(email: TChilkatBase): Boolean;` |
| `Clear` | method | `procedure Clear;` |
| `EmailAt` | method | `// email is a TEmail object. function EmailAt(index: Integer;     email: TChilkatBase): Boolean;` |
| `FindEmail` | method | `// json is a TJsonObject object. // email is a TEmail object. function FindEmail(json: TChilkatBase;     email: TChilkatBase): Boolean;` |
| `GetXml` | method | `function GetXml: string;` |
| `LoadTaskResult` | method | `// task is a TTask object. function LoadTaskResult(task: TChilkatBase): Boolean;` |
| `LoadXml` | method | `function LoadXml(const path: string): Boolean;` |
| `LoadXmlString` | method | `function LoadXmlString(const xmlStr: string): Boolean;` |
| `RemoveEmail` | method | `// email is a TEmail object. function RemoveEmail(email: TChilkatBase): Boolean;` |
| `RemoveEmailByIndex` | method | `function RemoveEmailByIndex(index: Integer): Boolean;` |
| `SaveXml` | method | `function SaveXml(const path: string): Boolean;` |
| `SortByDate` | method | `procedure SortByDate(ascending: Boolean);` |
| `SortByRecipient` | method | `procedure SortByRecipient(ascending: Boolean);` |
| `SortBySender` | method | `procedure SortBySender(ascending: Boolean);` |
| `SortBySubject` | method | `procedure SortBySubject(ascending: Boolean);` |

## Properties

### EmailBundle.MessageCount

`Chilkat 11.7.0 · pascal · EmailBundle · MessageCount · property · read-only`

```pascal
property MessageCount: Integer read GetMessageCount;
```

Returns the number of `Email` objects currently contained in the bundle.

Valid zero-based indexes range from `0` through `MessageCount - 1`.

## Methods

### EmailBundle.AddEmail

`Chilkat 11.7.0 · pascal · EmailBundle · AddEmail · method`

```pascal
// email is a TEmail object.

function  AddEmail(email: TChilkatBase): Boolean;
```

Adds an independent copy of the `Email` object in `email` to the end of this in-memory bundle.

The bundle does not retain a reference to `email` and does not take ownership of the supplied object. Changes made to `email` after this method returns do not affect the copy stored in the bundle, and changes to the stored copy do not affect `email`.

The same `Email` object may be added more than once. Each call adds another independent copy and increases the `MessageCount` property by one.

Returns True for success, False for failure.

### EmailBundle.Clear

`Chilkat 11.7.0 · pascal · EmailBundle · Clear · method · since 11.1.0`

```pascal
procedure Clear;
```

Removes and discards all emails from this in-memory bundle.

After this method returns, `MessageCount` is `0`. No messages are deleted from any mail server.

### EmailBundle.EmailAt

`Chilkat 11.7.0 · pascal · EmailBundle · EmailAt · method · since 11.0.0`

```pascal
// email is a TEmail object.

function  EmailAt(index: Integer;
    email: TChilkatBase): Boolean;
```

Copies the email at the zero-based index in `index` into the `Email` object in `email`.

Valid indexes range from `0` through `MessageCount - 1`. The first email is at index `0`.

`email` receives an independent copy. Changes made to `email` do not modify the email stored in the bundle.

**Note:** This is an in-memory operation and does not communicate with a mail server.

Returns True for success, False for failure.

### EmailBundle.FindEmail

`Chilkat 11.7.0 · pascal · EmailBundle · FindEmail · method · since 11.0.0`

```pascal
// json is a TJsonObject object.

// email is a TEmail object.

function  FindEmail(json: TChilkatBase;
    email: TChilkatBase): Boolean;
```

Finds the first email in the bundle whose MIME header field matches the search criteria specified by the `JsonObject` in `json`.

At this time, a search may specify only one MIME header field. Use the following JSON format:

```
{
  "header": {
    "name": "Subject",
    "value": "Dinner on Wednesday?",
    "caseInsensitive": true
  }
}
```

`header.name` specifies the MIME header field name, and `header.value` specifies the complete field value to match. The field value must match exactly; this is not a substring, wildcard, or regular-expression search. Set `header.caseInsensitive` to `true` for a case-insensitive comparison or `false` for a case-sensitive comparison.

When a match is found, `email` receives the first matching email.

Returns True for success, False for failure.

### EmailBundle.GetXml

`Chilkat 11.7.0 · pascal · EmailBundle · GetXml · method`

```pascal
function  GetXml: string;
```

Serializes the entire email bundle to Chilkat XML and returns the XML document as a string.

The XML contains the bundle and its individual `Email` objects. It can be loaded into another `EmailBundle` by calling `LoadXmlString`.

This is Chilkat's XML representation of an email bundle; it is not an RFC 822/MIME message.

Returns True for success, False for failure.

### EmailBundle.LoadTaskResult

`Chilkat 11.7.0 · pascal · EmailBundle · LoadTaskResult · method · since 9.5.0.52`

```pascal
// task is a TTask object.

function  LoadTaskResult(task: TChilkatBase): Boolean;
```

Loads this email bundle from the result of the completed asynchronous `Task` in `task`.

Use this method when an asynchronous Chilkat operation returns an `EmailBundle` as its task result. `task` must represent a task that has finished running.

Returns True for success, False for failure.

### EmailBundle.LoadXml

`Chilkat 11.7.0 · pascal · EmailBundle · LoadXml · method`

```pascal
function  LoadXml(const path: string): Boolean;
```

Loads an email bundle from the local filesystem path specified by `path`. The path may be absolute or relative; a filename alone refers to a file in the current working directory.

The file should contain Chilkat email-bundle XML previously produced by `SaveXml` or `GetXml`.

The emails loaded from `path` are appended to the emails already in the bundle. Existing emails are not removed or replaced.

Returns True for success, False for failure.

### EmailBundle.LoadXmlString

`Chilkat 11.7.0 · pascal · EmailBundle · LoadXmlString · method`

```pascal
function  LoadXmlString(const xmlStr: string): Boolean;
```

Loads an email bundle from the Chilkat XML string in `xmlStr`.

The XML is typically obtained from `GetXml` or read from a file created by `SaveXml`.

The emails loaded from `xmlStr` are appended to the emails already in the bundle. Existing emails are not removed or replaced.

Returns True for success, False for failure.

### EmailBundle.RemoveEmail

`Chilkat 11.7.0 · pascal · EmailBundle · RemoveEmail · method`

```pascal
// email is a TEmail object.

function  RemoveEmail(email: TChilkatBase): Boolean;
```

Removes the first email in this in-memory bundle that matches `email`.

Chilkat first searches for an email having the same UIDL as `email`. If no email with a matching UIDL is found, it searches for the first email having the same `Message-ID` header field value. Only the first matching email is removed.

`email` may be an independent copy obtained from `EmailAt`.

**Note:** This method changes only the local bundle. It does not delete a message from a POP3 or IMAP server.

Returns True for success, False for failure.

### EmailBundle.RemoveEmailByIndex

`Chilkat 11.7.0 · pascal · EmailBundle · RemoveEmailByIndex · method`

```pascal
function  RemoveEmailByIndex(index: Integer): Boolean;
```

Removes the email at the zero-based index in `index`.

Valid indexes range from `0` through `MessageCount - 1`.

**Note:** This method changes only the local bundle. It does not delete a message from a mail server.

Returns True for success, False for failure.

### EmailBundle.SaveXml

`Chilkat 11.7.0 · pascal · EmailBundle · SaveXml · method`

```pascal
function  SaveXml(const path: string): Boolean;
```

Serializes the bundle and each contained `Email` to Chilkat XML, then writes the XML document to the local filesystem path specified by `path`. The path may be absolute or relative; a filename alone writes to the current working directory.

Reload the saved bundle by calling `LoadXml`. Use `GetXml` when the XML is needed in memory rather than in a file.

The saved file is a Chilkat email-bundle serialization, not an RFC 822/MIME message file.

Returns True for success, False for failure.

### EmailBundle.SortByDate

`Chilkat 11.7.0 · pascal · EmailBundle · SortByDate · method`

```pascal
procedure SortByDate(ascending: Boolean);
```

Sorts the emails in this bundle by each `Email` object's `EmailDate` property.

Set `ascending` to `True` to sort in ascending order, from oldest to newest. Set `ascending` to `False` to sort in descending order, from newest to oldest.

The operation changes the order of the emails in the in-memory collection.

### EmailBundle.SortByRecipient

`Chilkat 11.7.0 · pascal · EmailBundle · SortByRecipient · method`

```pascal
procedure SortByRecipient(ascending: Boolean);
```

Sorts the emails in this bundle by the full value of each email's `To` header field.

The comparisons are case-sensitive. Set `ascending` to `True` for ascending order or `False` for descending order. The operation changes the order of the emails in the in-memory collection.

### EmailBundle.SortBySender

`Chilkat 11.7.0 · pascal · EmailBundle · SortBySender · method`

```pascal
procedure SortBySender(ascending: Boolean);
```

Sorts the emails in this bundle by the full content of each email's `From` header field.

Set `ascending` to `True` for ascending order or `False` for descending order. The operation changes the order of the emails in the in-memory collection.

### EmailBundle.SortBySubject

`Chilkat 11.7.0 · pascal · EmailBundle · SortBySubject · method`

```pascal
procedure SortBySubject(ascending: Boolean);
```

Sorts the emails in this bundle by subject.

Set `ascending` to `True` for ascending order or `False` for descending order. The operation changes the order of the emails in the in-memory collection.

## Related classes

[`Email`](https://www.chilkatsoft.com/ai-docs/v/11.7.0/pascal/classes/Email.md), [`JsonObject`](https://www.chilkatsoft.com/ai-docs/v/11.7.0/pascal/classes/JsonObject.md)