---
product: Chilkat
product_version: 11.7.0
language: delphidll
language_label: Delphi DLL
class: EmailBundle
license: bundle
deprecated: false
reference_html: https://www.chilkatsoft.com/refdoc/dd_CkEmailBundleRef.html
---
# Chilkat EmailBundle — Delphi DLL — v11.7.0

> Chilkat 11.7.0 · language=delphidll · 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/delphidll/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/Dispose**

```pascal
var
myObject: HCkEmailBundle;

begin
myObject := CkEmailBundle_Create();

// ...

CkEmailBundle_Dispose(myObject);
end;
```

`function CkEmailBundle_Create: HCkEmailBundle; stdcall;`

Creates an instance of the HCkEmailBundle object and returns a handle (i.e. a Pointer). The handle is passed in the 1st argument for the functions listed on this page.

`procedure CkEmailBundle_Dispose(handle: HCkEmailBundle); stdcall;`

Objects created by calling CkEmailBundle_Create must be freed by calling this method. A memory leak occurs if a handle is not disposed by calling this function.

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 Delphi DLL.

## 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` | `procedure CkEmailBundle_getDebugLogFilePath(objHandle: HCkEmailBundle; outPropVal: HCkString); stdcall; procedure CkEmailBundle_putDebugLogFilePath(objHandle: HCkEmailBundle; newPropVal: PWideChar); stdcall; function CkEmailBundle__debugLogFilePath(objHandle: HCkEmailBundle): PWideChar; stdcall;` | 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` | `procedure CkEmailBundle_getLastErrorHtml(objHandle: HCkEmailBundle; outPropVal: HCkString); stdcall; function CkEmailBundle__lastErrorHtml(objHandle: HCkEmailBundle): PWideChar; stdcall;` | read-only | Provides HTML-formatted information about the last called method or property. |
| `LastErrorText` | `procedure CkEmailBundle_getLastErrorText(objHandle: HCkEmailBundle; outPropVal: HCkString); stdcall; function CkEmailBundle__lastErrorText(objHandle: HCkEmailBundle): PWideChar; stdcall;` | read-only | Provides plain text information about the last called method or property. |
| `LastErrorXml` | `procedure CkEmailBundle_getLastErrorXml(objHandle: HCkEmailBundle; outPropVal: HCkString); stdcall; function CkEmailBundle__lastErrorXml(objHandle: HCkEmailBundle): PWideChar; stdcall;` | read-only | Provides XML-formatted information about the last called method or property. |
| `LastMethodSuccess` | `function CkEmailBundle_getLastMethodSuccess(objHandle: HCkEmailBundle): wordbool; stdcall; procedure CkEmailBundle_putLastMethodSuccess(objHandle: HCkEmailBundle; newPropVal: wordbool); stdcall;` | read/write | Indicates the success or failure of the most recent method call: `True` means success, `False` means failure. |
| `VerboseLogging` | `function CkEmailBundle_getVerboseLogging(objHandle: HCkEmailBundle): wordbool; stdcall; procedure CkEmailBundle_putVerboseLogging(objHandle: HCkEmailBundle; newPropVal: wordbool); stdcall;` | read/write | If set to `True`, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. |
| `Version` | `procedure CkEmailBundle_getVersion(objHandle: HCkEmailBundle; outPropVal: HCkString); stdcall; function CkEmailBundle__version(objHandle: HCkEmailBundle): PWideChar; stdcall;` | read-only | Version of the component/library, such as "10.1.0" |

## Member index

| Member | Kind | Signature |
|---|---|---|
| `MessageCount` | property, read-only | `function CkEmailBundle_getMessageCount(objHandle: HCkEmailBundle): Integer; stdcall;` |
| `AddEmail` | method | `function CkEmailBundle_AddEmail(objHandle: HCkEmailBundle;     email: HCkEmail): wordbool; stdcall;` |
| `Clear` | method | `procedure CkEmailBundle_Clear(objHandle: HCkEmailBundle) stdcall;` |
| `EmailAt` | method | `function CkEmailBundle_EmailAt(objHandle: HCkEmailBundle;     index: Integer;     email: HCkEmail): wordbool; stdcall;` |
| `FindEmail` | method | `function CkEmailBundle_FindEmail(objHandle: HCkEmailBundle;     json: HCkJsonObject;     email: HCkEmail): wordbool; stdcall;` |
| `GetXml` | method | `function CkEmailBundle_GetXml(objHandle: HCkEmailBundle;     outXml: HCkString): wordbool; stdcall; function CkEmailBundle__getXml(objHandle: HCkEmailBundle): PWideChar; stdcall;` |
| `LoadTaskResult` | method | `function CkEmailBundle_LoadTaskResult(objHandle: HCkEmailBundle;     task: HCkTask): wordbool; stdcall;` |
| `LoadXml` | method | `function CkEmailBundle_LoadXml(objHandle: HCkEmailBundle;     path: PWideChar): wordbool; stdcall;` |
| `LoadXmlString` | method | `function CkEmailBundle_LoadXmlString(objHandle: HCkEmailBundle;     xmlStr: PWideChar): wordbool; stdcall;` |
| `RemoveEmail` | method | `function CkEmailBundle_RemoveEmail(objHandle: HCkEmailBundle;     email: HCkEmail): wordbool; stdcall;` |
| `RemoveEmailByIndex` | method | `function CkEmailBundle_RemoveEmailByIndex(objHandle: HCkEmailBundle;     index: Integer): wordbool; stdcall;` |
| `SaveXml` | method | `function CkEmailBundle_SaveXml(objHandle: HCkEmailBundle;     path: PWideChar): wordbool; stdcall;` |
| `SortByDate` | method | `procedure CkEmailBundle_SortByDate(objHandle: HCkEmailBundle;     ascending: wordbool) stdcall;` |
| `SortByRecipient` | method | `procedure CkEmailBundle_SortByRecipient(objHandle: HCkEmailBundle;     ascending: wordbool) stdcall;` |
| `SortBySender` | method | `procedure CkEmailBundle_SortBySender(objHandle: HCkEmailBundle;     ascending: wordbool) stdcall;` |
| `SortBySubject` | method | `procedure CkEmailBundle_SortBySubject(objHandle: HCkEmailBundle;     ascending: wordbool) stdcall;` |

Deprecated members are listed at the end of this file with their replacements; do not use them in new code.

## Properties

### EmailBundle.MessageCount

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

```pascal
function CkEmailBundle_getMessageCount(objHandle: HCkEmailBundle): Integer; stdcall;
```

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 · delphidll · EmailBundle · AddEmail · method`

```pascal
function CkEmailBundle_AddEmail(objHandle: HCkEmailBundle;
    email: HCkEmail): wordbool; stdcall;
```

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 · delphidll · EmailBundle · Clear · method · since 11.1.0`

```pascal
procedure CkEmailBundle_Clear(objHandle: HCkEmailBundle) stdcall;
```

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 · delphidll · EmailBundle · EmailAt · method · since 11.0.0`

```pascal
function CkEmailBundle_EmailAt(objHandle: HCkEmailBundle;
    index: Integer;
    email: HCkEmail): wordbool; stdcall;
```

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 · delphidll · EmailBundle · FindEmail · method · since 11.0.0`

```pascal
function CkEmailBundle_FindEmail(objHandle: HCkEmailBundle;
    json: HCkJsonObject;
    email: HCkEmail): wordbool; stdcall;
```

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 · delphidll · EmailBundle · GetXml · method`

```pascal
function CkEmailBundle_GetXml(objHandle: HCkEmailBundle;
    outXml: HCkString): wordbool; stdcall;
function CkEmailBundle__getXml(objHandle: HCkEmailBundle): PWideChar; stdcall;
```

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.

See the notes about [PWideChar memory ownership and validity](https://www.chilkatsoft.com/delphi_pwidechar.asp).

### EmailBundle.LoadTaskResult

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

```pascal
function CkEmailBundle_LoadTaskResult(objHandle: HCkEmailBundle;
    task: HCkTask): wordbool; stdcall;
```

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 · delphidll · EmailBundle · LoadXml · method`

```pascal
function CkEmailBundle_LoadXml(objHandle: HCkEmailBundle;
    path: PWideChar): wordbool; stdcall;
```

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 · delphidll · EmailBundle · LoadXmlString · method`

```pascal
function CkEmailBundle_LoadXmlString(objHandle: HCkEmailBundle;
    xmlStr: PWideChar): wordbool; stdcall;
```

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 · delphidll · EmailBundle · RemoveEmail · method`

```pascal
function CkEmailBundle_RemoveEmail(objHandle: HCkEmailBundle;
    email: HCkEmail): wordbool; stdcall;
```

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 · delphidll · EmailBundle · RemoveEmailByIndex · method`

```pascal
function CkEmailBundle_RemoveEmailByIndex(objHandle: HCkEmailBundle;
    index: Integer): wordbool; stdcall;
```

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 · delphidll · EmailBundle · SaveXml · method`

```pascal
function CkEmailBundle_SaveXml(objHandle: HCkEmailBundle;
    path: PWideChar): wordbool; stdcall;
```

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 · delphidll · EmailBundle · SortByDate · method`

```pascal
procedure CkEmailBundle_SortByDate(objHandle: HCkEmailBundle;
    ascending: wordbool) stdcall;
```

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 · delphidll · EmailBundle · SortByRecipient · method`

```pascal
procedure CkEmailBundle_SortByRecipient(objHandle: HCkEmailBundle;
    ascending: wordbool) stdcall;
```

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 · delphidll · EmailBundle · SortBySender · method`

```pascal
procedure CkEmailBundle_SortBySender(objHandle: HCkEmailBundle;
    ascending: wordbool) stdcall;
```

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 · delphidll · EmailBundle · SortBySubject · method`

```pascal
procedure CkEmailBundle_SortBySubject(objHandle: HCkEmailBundle;
    ascending: wordbool) stdcall;
```

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.

## Deprecated members — do not use in new code

| Member | Kind | Deprecated in | Use instead |
|---|---|---|---|
| `FindByHeader` | method | before 11.6.1 | `FindEmail` |
| `GetEmail` | method | before 11.6.1 | `EmailAt` |
| `GetUidls` | method | before 11.6.1 | — |

## Related classes

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