OLE Automation in AK-Mail ------------------------- 1. Overview With the new release of AK-Mail, AK-Mail can be controlled by OLE automation. That means that a subset of the AK-Mail functionality is available to external software. This feature is only available in the registered version. Please make sure that you are familiar with the OLE automation technology. This reference cannot and will not explain any OLE automation terms. The functions AK-Mail offers are divided into 3 groups as follows: 1.) Functions to create a new outgoing mail Functions in this group allow you to place a new outgoing mail in the outbox of any account. This is especially useful for sending customized mail that goes to many people. Applications include sending of on demand data or registration keys for software. The functions can also be used to send highly customized mass mails. 2.) Functions to examine folders Functions to move/copy/delete messages Gives your own programs reading access to any folder. You can get a list of messages in a folder and you can retrieve header and body information of messages. There is no access to attachments. There is no access to outgoing messages. The functions are useful if you wish to automatically respond to incoming mail in a way too specific for AK-Mail filters. Because logic is in your external program there is nearly no limit on how to use the information that the incoming messages provide. 3.) Functions to examine entries in address books Functions to create/delete entries Gives you access to entries in address books. Lets you create new address book entries in any address book. 2. Basic Operation The object name of AK-Mail is 'akmail.application' (without '). If an object of this type already exists, you have to use that object. Please check in your application. Creation of another object will fail. The type library is stored in the akmail.exe file. Whenever a method returns a value it is an error code. A value of zero means success, any other value means that the method failed. For a list of error codes see Appendix A. Please note: The interface described in this file is subject to change without notice. OLE automation with AK-Mail is easy to use. Have fun! 3. Reference This reference part documents all methods and properties available in AK-Mail. Syntax used is pseudo C++ / pseudo VB style. 1. Group: Functions to create a new outgoing mail Methods: long StoreNewMail(BSTR account) Parameters: account = String that contains an account name. The new mail will be stored in the outbox of that account. What it does: StoreNewMail creates a new mail in the outbox of the given account. The following properties are used to generate the mail: ToField, CcField, BccField, Subject, Body Load the properties shown above with the values you wish to use for the new mail. Then call StoreNewMail. long StoreNewMailOptions(BSTR account,long options) Parameters: account = String that contains an account name. The new mail will be stored in the outbox of that account. options = Bitfield value, specifies additional options Bit 0 ..... Set stop mark Bit 1 ..... Encrypt using PGP Bit 2 ..... Sign using PGP Bit 3 ..... Return receipt Bit 4-31 ..... currently not used What it does: StoreNewMailOptions is the same as StoreNewMail with the additional options parameter. long StoreNewMailAtt(BSTR account,BSTR attachment) long StoreNewMailAttOptions(BSTR account,BSTR attachment,long options) Parameters: account = String that contains an account name. The new mail will be stored in the outbox of that account. attachment = One or more attachments to attach to the new mail. Specify the full filename (for example "c:\dir1\dir2\file.ext"). Separate multiple attachments through semicolons (for example "c:\file1;c:\file2"). options = Bitfield value, specifies additional options. See above for details. What it does: StoreNewMailAtt and StoreNewMailAttOptions are extensions of StoreNewMail and StoreNewMailOptions. They allow you to attach files to the new mail. Properties: BSTR ToField Stores the string that is to be placed in the To: field of a new outgoing mail. Separate multiple recipients by a comma or a new line character. Alias names are allowed. In general everything that is allowed in the composer window of AK-Mail is allowed here too. BSTR CcField Same as ToField but for Cc: field. BSTR BccField Same as ToField but for Bcc: field. BSTR Subject Stores the subject that is to be placed in the Subject: field of a new outgoing mail. This property is used by group 2 functions also. BSTR Body Stores the body that is to be used for the creation of the new mail. To use multiple lines of text you can use the new line character. The following two character sequences are recognized as new line indicator: a) 0x0A b) 0x0D 0x0A This property is used by group 2 functions also. Example: akmobj.ToField="testuser@testdomain.com" akmobj.CcField="" akmobj.BccField="" akmobj.Subject="Just a test" akmobj.Body="This is the body of the mail" akmobj.StoreNewMail "MyAccount" 2. Group: Functions to examine folders Methods: long ScanFolder(BSTR folderpath) Parameters: folderpath = String that contains a full path to a folder. A full path starts with an account name or '/' for the special folder. Examples are: AccountFoo/Folder/SubFolder/SubSubFolder /UnboundFolder/Child See the example for details. What it does: ScanFolder locates the folder using the folderpath parameter. If found, it scans the whole folder. Scanning means that it creates an internal list of messages that are in the folder. Only incoming messages are scanned and processed. The purpose of the function is to make an index available to other functions. For example if there are 400 incoming and 600 outgoing message in the folder, ScanFolder creates an internal list (index) that contains 400 elements. Other functions can access the list using an index integer in the range of 0 to 399 (0<=index<=399). long GetMail(long index) Parameters: index = Zero-based index for the internal list created by ScanFolder What it does: GetMail takes the given index and loads the message that is indexed through the index value into the properties described below. long DeleteMail(long index) Parameters: index = Zero-based index of mail to be deleted What it does: The mail with the given index is deleted. This operation does NOT modify the index. Attempt to delete a message twice will fail. Attempt to access a deleted message will fail. long DeleteMailUseTrash(long index) long DeleteMailDoNotUseTrash(long index) Parameters: index = Zero-based index of mail to be deleted What it does: Same as DeleteMail but overrides the behavior set in the account settings. DeleteMailUseTrash behaves as if the option in the account settings was not checked. DeleteMailDoNotUseTrash deletes mail immedialety without moving to the trash. long MoveMail(long index,BSTR topath) long CopyMail(long index,BSTR topath) Parameters: index = Zero-based index of the mail to be moved/copied topath = Full path to destination folder. See folderpath parameter of ScanFolder. What it does: The mail with the given index is moved/copied to the destination folder. This operation does not modify in index. Properties: BSTR FromEmail After GetMail this property contains the email address of the sender (for example 'gs@mynet.com'). The property is read-only. Writing to it will not cause an exception but has no effect. BSTR FromRealName After GetMail this property contains the real name of the sender (for example 'Gary Sanders'). Read-only. BSTR Subject After GetMail this property contains the subject of the mail. This property is also used by group 1 functions. BSTR Body After GetMail this property contains the body of the mail. Multiple lines are separated by 0x0D 0x0A. NOTE: This property is delayed. That means that GetMail does not load the value immediately. The first reading access to Body loads the value. So the speed of execution is greatly increased because the body and header of a mail is loaded on demand. If you do not need the body or header information it is not loaded. This property is also used by group 1 functions. BSTR Header After GetMail this property contains the header of the mail. Multiple lines are separated by 0x0D 0x0A. Like Body the property is delayed. This property is also used by group 1 functions. long MailCount After ScanFolder this property contains the number of elements in the index. That is the number of incoming messages in the folder. Read-only. Example: akmobj.ScanFolder "MyAccount/Inbox/FromMyCustomerA" ' ' You can access the special folder if the first character is ' a '/' ' ' akmobj.ScanFolder "/SpecialFolderXYZ" ' for i=0 to akmobj.MailCount-1 akmobj.GetMail(i) print akmobj.FromEmail print akmobj.FromRealName print akmobj.Subject print akmobj.Body print akmobj.Header next i 3. Group: Functions to examine address books Functions to create/delete entries Methods: long ScanBook(BSTR bookname) Parameters: bookname = String containing a name of a book What is does: ScanBook is the same as ScanFolder but for books. The index used for books is completely independend of the message index. long GetEntry(long index) Parameters: index = Zero-based index of the entry in the book index What it does: GetEntry loads the entry identified by the index into the properties described below. long DeleteEntry(long index) Parameters: index = Zero-based index of entry to delete What it does: Deletes the entry identified by the index. This operation does not modify the index. long StoreNewEntry(BSTR bookname) Parameters: bookname = String containing a name of a book What it does: The function takes the values of the EntryName, EntryEmail, EntryAlias, EntryComment properties described below and creates a new entry of them. The new entry is stored in the given book. Properties: BSTR EntryName Name of the person stored in the entry BSTR EntryEmail Email address of the person stored in the entry BSTR EntryAlias Alias of the person stored in the entry BSTR EntryComment Comment of the person stored in the entry long EntryCount Number of entries in the book index. Read-only. Example: ' This shows how to list all entries in a book ' akmobj.ScanBook "MyBook" for i=0 to akmobj.EntryCount-1 akmobj.GetEntry(i) print akmobj.EntryName print akmobj.EntryEmail print akmobj.EntryAlias print akmobj.EntryComment next i ' This shows how to create a new entry ' akmobj.EntryName="Andreas Kinzler" akmobj.EntryEmail="akinzler@pobox.com" akmobj.EntryAlias="ak" akmobj.EntryComment="Author of AK-Mail" akmobj.StoreNewEntry "MyBook" 4. Appendix A - Error Codes 0 = Success 1 = AK-Mail is not registered, OLE Automation not available 2 = General Error 3 = Problem to resolve account name, no account with the given name exists 4 = Cannot store new mail because the ToField property string is empty 5 = Cannot store new mail because at least one email address is invalid 6 = Problem to resolve folder path, no such path or folder exists 7 = Problem to resolve book name, no book with the given name exists 8 = Invalid index value 9 = Invalid entry alias 10 = Invalid entry email address 11 = Invalid entry name