---
product: Chilkat
product_version: 11.7.0
language: sqlserver
language_label: SQL Server
class: EmailBundle
license: bundle
deprecated: false
reference_html: https://www.chilkatsoft.com/refdoc/sqlserver_EmailBundleRef.html
---
# Chilkat EmailBundle — SQL Server — v11.7.0

> Chilkat 11.7.0 · language=sqlserver · 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/sqlserver/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

**Object Creation**

```sql
DECLARE @hr int
DECLARE @emailBundle int
EXEC @hr = sp_OACreate 'Chilkat.EmailBundle', @emailBundle OUT
IF @hr <> 0
BEGIN
    PRINT 'Failed to create ActiveX component'
    RETURN
END

-- ... use @emailBundle ...

EXEC @hr = sp_OADestroy @emailBundle
```

T-SQL uses the Chilkat ActiveX through the OLE Automation stored procedures. They must be enabled once on the server (`EXEC sp_configure 'Ole Automation Procedures', 1; RECONFIGURE;`), and the Chilkat ActiveX registered must match the bitness of the SQL Server instance (64-bit for a 64-bit SQL Server). To bind to a specific major version of Chilkat, append the major version number to the ProgID, such as `sp_OACreate 'Chilkat.EmailBundle.11'` for Chilkat v11.\*.\*.

`sp_OACreate` returns an object token (an `int`) that is passed as the first argument of every `sp_OAMethod`, `sp_OAGetProperty` and `sp_OASetProperty` call, and released with `sp_OADestroy`. Objects returned by methods (such as an `HttpResponse` or `JsonObject`) are also tokens received through an `int` OUT parameter; they must likewise be destroyed, and the OUT parameter is `NULL` when the method fails to return an object. Objects passed as arguments are passed by their token. When an OLE Automation procedure itself fails (non-zero `@hr`), `sp_OAGetErrorInfo` describes the error.

Data types: strings are `nvarchar(4000)`; integers, booleans (1 or 0) and object tokens are `int`; dates are `datetime`. In the signatures on this page, `@success`, `@iResult`, `@sResult` and the like are the OUT variables receiving a method's return value, `@iValue` / `@sValue` receive or supply a property value, and the remaining `@` variables are the method's arguments in order.

A string returned through an OUT parameter is limited to 4000 characters. For longer values, retrieve the result as a result set into a table variable instead of an OUT parameter, for example `DECLARE @tmp TABLE (outputLine ntext)` followed by `INSERT INTO @tmp EXEC sp_OAGetProperty @emailBundle, 'LastErrorText'`. See [string length limitations for strings returned by sp_OAMethod calls](https://www.chilkatsoft.com/sql_server_nvarchar_max_limitation.asp).

Methods that pass or return raw byte arrays are not shown on this page, because `varbinary(max)` values cannot be exchanged through `sp_OAMethod` (see [varbinary(max) limitation](https://www.chilkatsoft.com/sql_server_varbinary_max_limitation.asp)). Use the `BinData`-based alternatives (methods ending in *Bd*) or the base64 / hex string-encoded variants instead. Binary *properties* (such as `LastBinaryResult`) can be retrieved as a result set into a table variable, as shown in their signatures. Asynchronous (*\*Async*) methods and event callbacks are not available from SQL Server.

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 SQL Server.

How failure is reported depends on the method's return type and is stated in the note under each method below. In every case the diagnostic text is in the `LastErrorText` property of the object whose method was called.

## 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` | `EXEC sp_OAGetProperty @emailBundle, 'DebugLogFilePath', @sValue OUT EXEC sp_OASetProperty @emailBundle, 'DebugLogFilePath', @sValue` | read/write | If set to a file path, this property logs the LastErrorText of each Chilkat method or property call to the specified file. |
| `LastBinaryResult` | `INSERT INTO @tmp EXEC sp_OAGetProperty @emailBundle, 'LastBinaryResult'` | read-only | This property is mainly used in SQL Server stored procedures to retrieve binary data from the last method call that returned binary data. |
| `LastErrorHtml` | `EXEC sp_OAGetProperty @emailBundle, 'LastErrorHtml', @sValue OUT` | read-only | Provides HTML-formatted information about the last called method or property. |
| `LastErrorText` | `EXEC sp_OAGetProperty @emailBundle, 'LastErrorText', @sValue OUT` | read-only | Provides plain text information about the last called method or property. |
| `LastErrorXml` | `EXEC sp_OAGetProperty @emailBundle, 'LastErrorXml', @sValue OUT` | read-only | Provides XML-formatted information about the last called method or property. |
| `LastMethodSuccess` | `EXEC sp_OAGetProperty @emailBundle, 'LastMethodSuccess', @iValue OUT EXEC sp_OASetProperty @emailBundle, 'LastMethodSuccess', @iValue` | read/write | Indicates the success or failure of the most recent method call: `1` means success, `0` means failure. |
| `LastStringResult` | `EXEC sp_OAGetProperty @emailBundle, 'LastStringResult', @sValue OUT` | read-only | In SQL Server stored procedures, this property holds the string return value of the most recent method call that returns a string. |
| `LastStringResultLen` | `EXEC sp_OAGetProperty @emailBundle, 'LastStringResultLen', @iValue OUT` | read-only | The length, in characters, of the string contained in the LastStringResult property. |
| `VerboseLogging` | `EXEC sp_OAGetProperty @emailBundle, 'VerboseLogging', @iValue OUT EXEC sp_OASetProperty @emailBundle, 'VerboseLogging', @iValue` | read/write | If set to `1`, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. |
| `Version` | `EXEC sp_OAGetProperty @emailBundle, 'Version', @sValue OUT` | read-only | Version of the component/library, such as "10.1.0" |

## Member index

| Member | Kind | Signature |
|---|---|---|
| `MessageCount` | property, read-only | `EXEC sp_OAGetProperty @emailBundle, 'MessageCount', @iValue OUT` |
| `AddEmail` | method | `EXEC sp_OAMethod @emailBundle, 'AddEmail', @success OUT, @email` |
| `Clear` | method | `EXEC sp_OAMethod @emailBundle, 'Clear', NULL` |
| `EmailAt` | method | `EXEC sp_OAMethod @emailBundle, 'EmailAt', @success OUT, @index, @email` |
| `FindEmail` | method | `EXEC sp_OAMethod @emailBundle, 'FindEmail', @success OUT, @json, @email` |
| `GetXml` | method | `EXEC sp_OAMethod @emailBundle, 'GetXml', @sResult OUT` |
| `LoadXml` | method | `EXEC sp_OAMethod @emailBundle, 'LoadXml', @success OUT, @path` |
| `LoadXmlString` | method | `EXEC sp_OAMethod @emailBundle, 'LoadXmlString', @success OUT, @xmlStr` |
| `RemoveEmail` | method | `EXEC sp_OAMethod @emailBundle, 'RemoveEmail', @success OUT, @email` |
| `RemoveEmailByIndex` | method | `EXEC sp_OAMethod @emailBundle, 'RemoveEmailByIndex', @success OUT, @index` |
| `SaveXml` | method | `EXEC sp_OAMethod @emailBundle, 'SaveXml', @success OUT, @path` |
| `SortByDate` | method | `EXEC sp_OAMethod @emailBundle, 'SortByDate', NULL, @ascending` |
| `SortByRecipient` | method | `EXEC sp_OAMethod @emailBundle, 'SortByRecipient', NULL, @ascending` |
| `SortBySender` | method | `EXEC sp_OAMethod @emailBundle, 'SortBySender', NULL, @ascending` |
| `SortBySubject` | method | `EXEC sp_OAMethod @emailBundle, 'SortBySubject', NULL, @ascending` |

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 · sqlserver · EmailBundle · MessageCount · property · read-only`

```sql
EXEC sp_OAGetProperty @emailBundle, 'MessageCount', @iValue OUT
```

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

```sql
EXEC sp_OAMethod @emailBundle, 'AddEmail', @success OUT, @email
```

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 1 for success, 0 for failure.

### EmailBundle.Clear

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

```sql
EXEC sp_OAMethod @emailBundle, 'Clear', NULL
```

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

```sql
EXEC sp_OAMethod @emailBundle, 'EmailAt', @success OUT, @index, @email
```

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 1 for success, 0 for failure.

### EmailBundle.FindEmail

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

```sql
EXEC sp_OAMethod @emailBundle, 'FindEmail', @success OUT, @json, @email
```

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 1 for success, 0 for failure.

### EmailBundle.GetXml

`Chilkat 11.7.0 · sqlserver · EmailBundle · GetXml · method`

```sql
EXEC sp_OAMethod @emailBundle, 'GetXml', @sResult OUT
```

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 `NULL` on failure

### EmailBundle.LoadXml

`Chilkat 11.7.0 · sqlserver · EmailBundle · LoadXml · method`

```sql
EXEC sp_OAMethod @emailBundle, 'LoadXml', @success OUT, @path
```

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 1 for success, 0 for failure.

### EmailBundle.LoadXmlString

`Chilkat 11.7.0 · sqlserver · EmailBundle · LoadXmlString · method`

```sql
EXEC sp_OAMethod @emailBundle, 'LoadXmlString', @success OUT, @xmlStr
```

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 1 for success, 0 for failure.

### EmailBundle.RemoveEmail

`Chilkat 11.7.0 · sqlserver · EmailBundle · RemoveEmail · method`

```sql
EXEC sp_OAMethod @emailBundle, 'RemoveEmail', @success OUT, @email
```

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 1 for success, 0 for failure.

### EmailBundle.RemoveEmailByIndex

`Chilkat 11.7.0 · sqlserver · EmailBundle · RemoveEmailByIndex · method`

```sql
EXEC sp_OAMethod @emailBundle, 'RemoveEmailByIndex', @success OUT, @index
```

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 1 for success, 0 for failure.

### EmailBundle.SaveXml

`Chilkat 11.7.0 · sqlserver · EmailBundle · SaveXml · method`

```sql
EXEC sp_OAMethod @emailBundle, 'SaveXml', @success OUT, @path
```

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 1 for success, 0 for failure.

### EmailBundle.SortByDate

`Chilkat 11.7.0 · sqlserver · EmailBundle · SortByDate · method`

```sql
EXEC sp_OAMethod @emailBundle, 'SortByDate', NULL, @ascending
```

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

Set `ascending` to `1` to sort in ascending order, from oldest to newest. Set `ascending` to `0` 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 · sqlserver · EmailBundle · SortByRecipient · method`

```sql
EXEC sp_OAMethod @emailBundle, 'SortByRecipient', NULL, @ascending
```

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 `1` for ascending order or `0` for descending order. The operation changes the order of the emails in the in-memory collection.

### EmailBundle.SortBySender

`Chilkat 11.7.0 · sqlserver · EmailBundle · SortBySender · method`

```sql
EXEC sp_OAMethod @emailBundle, 'SortBySender', NULL, @ascending
```

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

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

### EmailBundle.SortBySubject

`Chilkat 11.7.0 · sqlserver · EmailBundle · SortBySubject · method`

```sql
EXEC sp_OAMethod @emailBundle, 'SortBySubject', NULL, @ascending
```

Sorts the emails in this bundle by subject.

Set `ascending` to `1` for ascending order or `0` 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/sqlserver/classes/Email.md), [`JsonObject`](https://www.chilkatsoft.com/ai-docs/v/11.7.0/sqlserver/classes/JsonObject.md)

