EmailBundle Zig Reference Documentation

EmailBundle

Current Version: 11.6.1

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.

Object Creation

// Add the package once:
//     zig fetch --save https://chilkatdownload.com/11.6.1/chilkat-zig-11.6.1.tar.gz
// and in build.zig:
//     const chilkat = b.dependency("chilkat", .{ .target = target, .optimize = optimize });
//     exe.root_module.addImport("chilkat", chilkat.module("chilkat"));
const chilkat = @import("chilkat");

// Once per process, before any other Chilkat call:
try chilkat.unlockBundle("Anything for 30-day trial");

const email_bundle = try chilkat.EmailBundle.init();
defer email_bundle.deinit();

pub fn init() Allocator.Error!EmailBundle

Creates the underlying native Chilkat object. EmailBundle is a one-pointer struct passed by value; copying it copies the handle (two names for one object). Returns error.OutOfMemory if the library could not allocate the object. Use an object from one thread at a time; it may be handed from one thread to another.

pub fn deinit(self: EmailBundle) void

Releases the native object. Call it exactly once per object (usually with defer); the handle is invalid afterwards. Objects returned by methods are owned by the caller too and are released the same way.

pub fn fromHandle(h: *chilkat.c.CkEmailBundle.HCkEmailBundle) EmailBundle

Wraps a handle obtained from the C API (chilkat.c.CkEmailBundle), taking ownership of it. The struct's handle field goes the other way, for anything the Zig API does not cover.

Errors and memory

Methods that can fail return an error union: a method whose only outcome is success or failure returns Error!void; a method producing a string returns (Error || Allocator.Error)![:0]u8; a method producing an object returns Error!T. chilkat.Error is error{ChilkatFailed}; the reason for a failure is in getLastErrorText, and the object remains usable. Properties never fail, and methods that answer a question (hasMember, isUnlocked, ...) return a plain bool.

String arguments are [:0]const u8 (UTF-8; string literals can be passed as is). String results are copies allocated with the allocator argument and owned by the caller, so they stay valid across later calls on the same object.

const text = email_bundle.someMethod(allocator, ...) catch |err| {
    const why = try email_bundle.getLastErrorText(allocator);
    defer allocator.free(why);
    std.debug.print("{s}\n", .{why});
    return err;
};
defer allocator.free(text);

Properties

DebugLogFilePath

// read/write
pub fn getDebugLogFilePath(self: EmailBundle, allocator: Allocator) Allocator.Error![:0]u8
pub fn setDebugLogFilePath(self: EmailBundle, value: [:0]const u8) void

If set to a file path, this property logs the LastErrorText of each Chilkat method or property call to the specified file. This logging helps identify the context and history of Chilkat calls leading up to any crash or hang, aiding in debugging.

Enabling the VerboseLogging property provides more detailed information. This property is mainly used for debugging rare instances where a Chilkat method call causes a hang or crash, which should generally not happen.

Possible causes of hangs include:

A timeout property set to 0, indicating an infinite timeout.
A hang occurring within an event callback in the application code.
An internal bug in the Chilkat code causing the hang.

More Information and Examples

EmailBundle Zig Reference Documentation

EmailBundle

Current Version: 11.6.1

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

Email collection

Retrieve messages

Search within the bundle

Sort messages

Remove or clear emails

Save and reload

Object Creation

Errors and memory

Properties

DebugLogFilePath

LastErrorHtml

LastErrorText

LastErrorXml

LastMethodSuccess

MessageCount

VerboseLogging

Version

Methods

AddEmail

Clear

EmailAt

FindEmail

GetXml

LoadXml

LoadXmlString

RemoveEmail

RemoveEmailByIndex

SaveXml

SortByDate

SortByRecipient

SortBySender

SortBySubject