EmailBundle JavaScript Reference Documentation
EmailBundle
Current Version: 11.5.0
Chilkat.EmailBundle
Store multiple
Use the message count and indexed access methods to retrieve individual
emails for inspection, processing, saving, or sending.
Locate a specific email in the collection when application logic needs
to find a matching message.
Sort the bundle by date, sender, recipient, or subject to organize
messages before processing or display.
Remove individual messages by object or index, or clear the entire
bundle when the collection is no longer needed.
Serialize the bundle to XML and reload it later, or load task results
that return an email bundle.
For an extended overview, see
EmailBundle Class Overview.
Hold, search, sort, remove, save, and reload groups of email messages.
Chilkat.EmailBundle is a container for multiple
Chilkat.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
Chilkat.Email objects together after
receiving, loading, filtering, or manually building a message set.
Retrieve messages
Search within the bundle
Sort messages
Remove or clear emails
Save and reload
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
Chilkat.Email for the individual message contents.
Object Creation
Note: This is intended for running within a Chilkat.Js embedded JavaScript engine.
var obj = new CkEmailBundle();
Properties
DebugLogFilePath
· string
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.
LastErrorHtml
·string,read-only
Provides HTML-formatted information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.
topLastErrorText
·string,read-only
Provides plain text information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.
LastErrorXml
·string,read-only
Provides XML-formatted information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.
topLastMethodSuccess
· boolean
Indicates the success or failure of the most recent method call: true means success, false means failure. This property remains unchanged by property setters or getters. This method is present to address challenges in checking for null or Nothing returns in certain programming languages. Note: This property does not apply to methods that return integer values or to boolean-returning methods where the boolean does not indicate success or failure.
MessageCount
·int,read-only
The number of emails in this bundle.
topVerboseLogging
· boolean
If set to true, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. The default value is false. Verbose logging should only be used for debugging. The potentially large quantity of logged information may adversely affect peformance.
Version
·string,read-only
Methods
AddEmail
· return:boolean;truefor success,falsefor failure
· email:CkEmail
Clear
· return: undefined
Removes and discards all emails contained in this object.
topEmailAt
· return:boolean;truefor success,falsefor failure
· index:int
· email:CkEmail
Copies the Nth email contained in this object into email. The 1st email is at index 0.
Returns true for success, false for failure.
topFindEmail
· return:boolean;truefor success,falsefor failure
· json:CkJsonObject
· email:CkEmail
Returns the first email from the bundle that matches the search criteria specified in json. This method, which replaces the deprecated FindByHeader method, currently offers the same functionality but can be expanded for additional search options in the future. The matching email, if found, is returned in email.
Returns true for success, false for failure.
topGetXml
· return: string
Converts the email bundle to an XML document in memory. Returns the XML document as a string.
Returns null on failure
LoadXml
· return:boolean;truefor success,falsefor failure
· filename:string
LoadXmlString
· return:boolean;truefor success,falsefor failure
· xmlStr:string
RemoveEmail
· return:boolean;truefor success,falsefor failure
· email:CkEmail
Removes an email from the bundle. This does not remove the email from the mail server.
Returns true for success, false for failure.
topRemoveEmailByIndex
· return:boolean;truefor success,falsefor failure
· index:int
Removes the Nth email in a bundle. (Indexing begins at 0.)
Returns true for success, false for failure.
topSaveXml
· return:boolean;truefor success,falsefor failure
· filename:string
Converts each email to XML and persists the bundle to an XML file. The email bundle can later be re-instantiated by calling MailMan.LoadXmlFile
Returns true for success, false for failure.
topSortByDate
· return:undefined
· ascending:boolean
Sorts emails in the bundle by date.
topSortByRecipient
· return:undefined
· ascending:boolean
Sorts emails in the bundle by recipient.
topSortBySender
· return:undefined
· ascending:boolean
Sorts emails in the bundle by sender.
topSortBySubject
· return:undefined
· ascending:boolean
Sorts emails in the bundle by subject.
top