ICONICO

Mailbox SDK Delphi Developers Guide

Interface Between any Email Client and Your Application

Mailbox SDK: MCore API for Delphi Developers Guide

How to, use MCore library API for Delphi application development.

Necessary files:
SDKFolder \ Bin \ MCore.dll - exporting MCore API.
SDKFolder \ Bin \ MCore.ini – the MCore settings file. If not available, the MCore.dll is configured by default.
SDKFolder \ Units \ MCoreInterface.pas - MCore API unit for Delphi.
SDKFolder \ Units \ MCoreTypes.pas - MCore data types descriptions and additional functions.

MCore.dll and MCore.ini must be located in the visibly area for the Delphi application - it can be application run folder, or Windows environment folder, like: ‘c:\windows’, ‘c:\Windows \ System32’, and so on.

First step: creating empty Delphi application with using MCore.dll.
Follow these steps:
1. Create a folder named 'MCoreSample'.
2. Put next files in to the 'MCoreSample' folder:
MCoreSample\MCore.dll
MCoreSample\MCore.ini
MCoreSample\MCore.pas
3. Run Delphi.
4. Create an empty application (File \ New \ Application).
5. Save application files to the 'MCoreSample' folder (File \ Save project as ...').
6. Add MCore.pas units to the application (Project \ Add to project ...)
7. Compile the application (Ctrl-F9).

You should get Delphi application that uses MCore.dll. Keep all application’s files in a separate folder, as you will need as harvesting for more complex projects.

Second step: Opening Mailbox file.
To open the Mailbox file using MCore API function OpenMailbox. The result of this function is a unique handle of opened Mailbox, or error code. All actions with Mailbox to be made with the handle, obtained when using OpenMailbox API. Perform actions on the Mailbox contents, can be only after you have opened the Mailbox. To complete work necessary to close Mailbox, with using MCore API function CloseMailbox.

Action 1.
Locate any Mailbox file and remember the path. To search for Mailbox files, use the utility SDKFolder \ Bin \ FindMailbox.exe.
Suppose that the full path and Mailbox file name: 'c: \ OutlookExress \ Folders.dbx'.

Action 2.
OpenMailbox API located in the unit file MCore.pas file. You need to connect the unit MCore.pas to your unit Unit1.pas:

unit Unit1;
interface
Uses
  Windows, Messages, SysUtils, Variants, Classes, Graphics, Controls,
  Forms, Dialogs, MCoreInterface;

Now, unit Unit1.pas available to use MCore API, exported by unit MCore.pas.

Action 3.

Put the button Button1 to your form Form1, and add the click event handler for Button1:

procedure TForm1.Button1Click(Sender: TObject); 
begin 
   OpenMailbox ( 'c:\OutlookExress\Folders.dbx'); 
end;

Compile the application, run it, and click Button1, this will lead to opening the Mailbox file 'C:\OutlookExress\Folders.dbx'. The result obtained after call OpenMailbox function is unknown, therefore add the result suit:

procedure TForm1.Button1Click (Sender: TObject); 
var 
  Handle :dword; 
begin 
  Handle := OpenMailbox ('c:\OutlookExress\Folders.dbx'); 
end;

Variable Handle gets the OpenMailbox function result, look at how it can be processed.

Action 4.

Error Codes:

· All Error Codes constants begin with the prefix 'OMS_'.

· Error Code 0 (OMS_OK) mean the MCore API successfully, in all cases except OpenMailbox. OpenMailbox returns as a result Handle successfully open Mailbox. If OpenMailbox return OMS_OK, it is seen as an error with a value 'NO_HANDLE'.

· OMS_NOERROR the last Error Code = 0F00h (3840dec), all of the Error Codes over the number seen as Handle and used OpenMailbox. If the result of the OpenMailbox, more than OMS_NOERROR, than the function, successfully open Mailbox. Otherwise returned an Error Code.

Add the following code:

procedure TForm1.Button1Click (Sender: TObject); 
var 
  Handle :dword; 
begin 
  Handle := OpenMailbox ('c:\OutlookExress\Folders.dbx'); 
  if Handle > OMS_NOERROR then ShowMessage ('Mailbox is open.') 
   else ShowMessage('Mailbox open error code:' + IntToStr (Handle)); 
end;

Action 5.

To close opened Mailbox use the CloseMailbox API function. The API transferring as a parameter Handle of opened Mailbox:

procedure TForm1.Button1Click (Sender: TObject); 
var 
  Handle :dword; 
begin 
  Handle := OpenMailbox ('c:\OutlookExress\Folders.dbx'); 
  if Handle > OMS_NOERROR then CloseMailbox (Handle) 
   else ShowMessage('Mailbox open error code:' + IntToStr (Handle)); 
end;

If Mailbox has been successfully opened, the CloseMailbox call will close it.
The following are a few variations of this code, all of which are considered to be correct in terms of MCore SDK, meaning they show the diversity of MCore API design:

for example:

procedure TForm1.Button1Click (Sender: TObject); 
var 
  MailboxHandle :dword; 
begin 
  MailboxHandle := MCore.OpenMailbox('c:\OutlookExress\Folders.dbx'); 
  if MailboxHandle > OMS_NOERROR then
   MCore.MCoreInterface.CloseMailbox (MailboxHandle) 
   else ShowMessage('Mailbox open error code:' + IntToStr(MailboxHandle)); 
end;

MCore CloseMailbox API returns the result, which can be analyzed:

procedure TForm1.Button1Click (Sender: TObject); 
var 
  Handle :dword; 
  CloseResult :dword; 
begin 
  Handle := OpenMailbox ('c:\OutlookExress\Folders.dbx'); 
  if Handle > OMS_NOERROR then ... 
   else ShowMessage('Mailbox open error code:' + IntToStr (Handle)); 
  CloseResult := CloseMailbox(Handle) 
  ShowMessage('Close result:' + IntToStr (CloseResult)); 
end;

For a more visible display of the results of the MCore APIs use the TokenizeErrorCode function described in the MCore .pas unit. As a parameter passed Error Code, the returned value is a string:

procedure TForm1.Button1Click (Sender: TObject); 
var 
  Handle :dword; 
  CloseResult :dword; 
begin 
  Handle: = OpenMailbox ( 'c:\OutlookExress\Folders.dbx'); 
  if Handle > OMS_NOERROR then ... 
   else ShowMessage ('Open error code:' + TokenizeErrorCode(Handle)); 
  CloseResult := CloseMailbox(Handle) 
  ShowMessage('Close result:' + TokenizeErrorCode (CloseResult)); 
end;

Third step: Getting the structure of the Open Mailbox folder.
To work with the folders you need to use two MCore API:

GetFolderCount - get the first folder.
GetFolderProp - get the next folder(s).
For both API parameter passed Handle of opened Mailbox.

Sequence API call is made:
If get the first folder GetFolderCount - 1 > 0 , than call GetFolderProp yet it possible.

The result of the API call is an error code and folder record containing information found on the regular folder. If GetFolderProp returned a result OMS_OK, then the folder record contains information, otherwise there is no more folders and search should be discontinued.

Action 1.

A simple example of using MCore API to search folders.
How to organized sequence Call GetFolderCount and GetFolderProp:

GetFolderCount will be called only once, GetFolderProp will be called until there is in the Mailbox folders.

procedure TForm1.Button1Click (Sender: TObject); 
var 
   Handle :dword; 
    FolderIndex: dword;  
    FolderProp : TFolderProp; 
 begin 
   Handle := OpenMailbox ('c:\OutlookExress\Folders.dbx'); 
   if Handle > OMS_NOERROR then 
   begin
     For FolderIndex = 0 to GetFolderCound(Handle)-1 do 
       Begin
         GetFolderProp(Handle, FolderIndex, FolderProp);
         //.. do something with folder properties in FolderProp record
       End;
      CloseMailbox(Handle); //-> Close opened mailbox 
   end 
   else 
     ShowMessage('Open mailbox error:' + TokenizeErrorCode (Handle)); 
end;

That is all that relates to the technical side of working with API to search folders. We propose to consider what useful information entry to TFolderProp record. Below is a description of the TFolderProp record:
Name-name of the folder
Path - is the path to the folder (like ‘Outlook Express\Local Folders\Inbox’)
FolderFile – Mailbox file.

Comment - commentary for the folder (MS Outlook)
ID - is a unique folder identifier.
ParentID - ID of the parent folder (for the root folder ParentID = 0).
MailCount - meter mails of the folder.
Size- size of folder in bytes.

The most useful fields are: Name, ID, ParentID, MailCount:

Name - name displayed in the user's email program.
ID - is a unique folder identifier, its role is not only that would distinguish one folder from another, Folder.ID in the same situation indicates folder in the hierarchy of folders, who belongs to the folder and what folders belong to it.
ParentID - unique identifier parent folders, thus knows folder inside a folder which it is situated.

Example hierarchy of folders with the values ID and ParentID:

Outlook Express (ID = 1; ParentID = 0)

Local Folders (ID = 2; ParentID = 1)

Inbox (ID = 3; ParentID = 2)

Outbox (ID = 4; ParentID = 2)

Temp Folder (ID = 5; ParentID = 4)

Sent Items (ID = 6; ParentID = 2)

Action 2.

Showing the folders inside opened Mailbox in TMemo.
Put the TMemo component on the Form1. To the previous example, add the following code:

procedure TForm1.Button1Click (Sender: TObject); 
var 
   Handle :dword;
    FolderIndex: dword;  
    FolderProp : TFolderProp; 
 begin
   Handle := OpenMailbox ('c:\OutlookExress\Folders.dbx'); 
   if Handle > OMS_NOERROR then 
   begin 
     For FolderIndex = 0 to GetFolderCound(Handle)-1 do 
       Begin
         GetFolderProp(Handle, FolderIndex, FolderProp);
         // Add folder data to Memo lines
         Memo.Lines.Add('Folder name:' FolderProp.Name +); 
         Memo.Lines.Add('ID:' + IntToStr (FolderProp.ID)); 
         Memo.Lines.Add('ParentID:' + IntToStr (FolderProp.ParentID)); 
         Memo.Lines.Add('Messages:' + IntToStr (FolderProp.MessagesCount)); 
       End;
      CloseMailbox(Handle); //-> Close opened mailbox 
   end 
   else 
     ShowMessage('Open mailbox error:' + TokenizeErrorCode (Handle)); 
end;

Step Four. Obtaining copies of mails from the folders.
To have access to the mails must do the following:

Open Mailbox with using OpenMailbox API.
List of open-Mailbox folders, with using GetFolderCount and GetFolderProp API.

To work with the mails MCore provides API functions group:

GetMailProp - get record with information about the contents of the mail.
GetMailBody - obtain a copy of the mail.
GetMail - get mail.
GetAttachCount - get a list of the attached files.
GetAttachProp -get attached file from the mail.

GetMail is the base MCore mail API function. It will provide access to the mail which is stored inside the Mailbox. Then you can realize all the mail contents processing with using only the GetMail. However, you can use the rest, the subsidiary API. MCore SDK provides a full service for mail processing that you may need, making it easier to work on your application.

Each MCore API associated with the handling of mail passed as parameters - Handle of opened Mailbox and Folder where the target mail locate. Each mail in Folder has a number, from 0 to FolderProp.MailCount-1. To list all the mails in the folder, it is necessary to alternately turn to each of them.

Action 1.

Enumeration of all the mails, inside all folders inside opened Mailbox.

procedure TForm1.Button1Click (Sender: TObject); 
var 
   Handle :dword; 
    FolderIndex, MailIndex: dword;  
    FolderProp : TFolderProp; 
    MailProp: TMailProp;  
begin 
   Handle := OpenMailbox ('c:\OutlookExress\Folders.dbx'); 
   if Handle > OMS_NOERROR then 
   begin 
     For FolderIndex = 0 to GetFolderCound(Handle)-1 do 
       Begin
         GetFolderProp(Handle, FolderIndex, FolderProp);
         // Add folder data to Memo lines
         Memo.Lines.Add('Folder name:' FolderProp.Name +); 
         Memo.Lines.Add('ID:' + IntToStr (FolderProp.ID)); 
         Memo.Lines.Add('ParentID:' + IntToStr (FolderProp.ParentID)); 
         Memo.Lines.Add('Messages:' + IntToStr (FolderProp.MessagesCount)); 
         //-> Enumerate mails inside folder 
         for MailIndex := 0 to FolderProp.MailCount-1 do
           if GetMailProp(Handle, Folder, MailIndex, MailProp) = OMS_OK
            then 
              Memo.Lines.Add('From name:' + MailProp.SenderName +
               'From address' MailProp.SenderAddr + '.eml'); 
       end;
      CloseMailbox(Handle); / /-> Close opened mailbox 
   end 
   else 
     ShowMessage('Open mailbox error:' + TokenizeErrorCode (Handle)); 
end;

In the example used only two fields TMailProp record, the following is a description of all the fields:

[warning: members can be non existant]

MessageID

unequal mail message identification number.

Header

RFC header, if present. Use GetMail API to get full mail message source code. [warning]

SenderName

sender name, like ‘John’ or ‘Bill’. Can be non existant. [warning]

SenderAddr

sender address, like ‘John@yahoo.com’ or ‘Bill@gmail.com’. Can be non existant. [warning]

RecipientNames

recipients names list, with ‘;’ separate char, like ‘Shon;Marry;’. [warning]

RecipientAddresses

recipients addresses list, with ‘;’ separate char, like ‘Shon@msn.com;Marry@mail.org;’. [warning]

carbon Copy list, with names and addresses, in ‘name1<address1>;name2<address2>’ format. [warning]

CCNames

carbon Copy names list.[warning]

CCAddresses

carbon Copy addresses list.[warning]

BCC

hided Carbon Copy list.[warning]

BCCNames

hided Carbon Copy names list. [warning]

BCCAddresses

hided Carbon Copy addresses list. [warning]

Subject

mail message subject. [warning]

NewsGroup

News Group flag, if ‘True’ the mail message is News Group message, can be not downloaded with zero length body.

HasAttach

if true, the mail message has attach. Use GetAttachCount like alternative.

Size

mail message size in bytes.

CreateDate

mail creating date time in Windows FileDateTime format

RecvDate

mail receiving date time in Windows FileDateTime format

Action 2.

Store mails copies, in separate files.
This example is taken from MCoreFolder \ Samples \ Delphi \ Email Backup \ Main.pas, and provides without changes:

procedure TForm2.Button3Click(Sender: TObject);
var
  Handle: dword;
  Folder: TFolderProp;
  MailData: TMailProp;
  Mail: pointer;
  MailStream: TMemoryStream;
  MailSize: int64;
  Path: string;
  i, j: integer;
begin
  if ComboBox1.Text = '' then
  begin
    ShowMessage('Please select Mailbox file.');
    Exit;
  end;

  if Edit2.Text = '' then
  begin
    ShowMessage('Please select Backup folder.');
    Exit;
  end;

  //-> Open mailbox
  Handle := OpenMailbox(PChar(ComboBox1.Text));

  if Handle > OMS_NOERROR then
  begin
    for j:= 0 to GetFolderCount(Handle)-1 do
    begin
        GetFolderProp(Handle, j, Folder);
        Path := Edit2.Text + Folder.Name + ' ' +
         IntToStr(Folder.ID) + '\';
        
        ForceDirectories(Path);
        
        //-> Enume mails inside folder
        for i := 0 to Folder.MailCount - 1 do
        begin
          if GetMailProp(Handle, j, i, MailData) = OMS_OK then
            if GetMailLength(Handle, j, i, MailSize) = OMS_OK then
            begin
              GetMem(Mail, MailSize);
              GetMail(Handle, j, i, Mail);
              //-> Store mail from memory buffer to disc file
              MailStream := TMemoryStream.Create;
              MailStream.Write(Mail^, MailSize);
              MailStream.Position := 0;
              MailStream.SaveToFile(Path + IntToStr(i + 1) +
               '.' + MailData.SenderAddr + '.eml');
              MailStream.Free;
              FreeMem(Mail);
              Label4.Caption := MailData.SenderAddr;
            end;
          Application.ProcessMessages;
        end;

       end;
     //-> Close opened mailbox
     CloseMailbox(Handle);
  end
  else
      ShowMessage('Open mailbox problem: ' + TokenizeErrorCode(Handle));
end;

Action 3.
Extracting the attached files for the mail. This example is taken from MCoreFolder \ Samples \ Delphi \ Mailbox Viewer \ MailboxViewUnit.pas, and provides without changes.

procedure TShowMailboxForm.Button1Click(Sender: TObject);
var
  Folder: PFolderProp;
  Attach: Pointer;
  Size: dword;
  AttachIndex: integer;
  AttachProp: TAttachProp;
  AttachMemoryStream: TMemoryStream;
  FileName: string;  
begin
 //Open attach file from mail

  //Are attach file is selected in attach combobox
  if ComboBox1.ItemIndex = -1 then exit;
  
  //Get current selected folder
  Folder := PFolderProp(TreeView.Selected.Data);
  AttachIndex := ComboBox1.ItemIndex;
  if GetAttachProp(MailboxHandle, Folder.Index,
   ListView1.Selected.Index, AttachIndex, AttachProp) = OMS_OK then

    if GetAttachLength(MailboxHandle, Folder.Index,
     ListView1.Selected.Index, AttachProp.Number, Size) = OMS_OK then

    begin
      FileName := string(AttachProp.FileName);
      if FileName = '' then FileName := 'noname.txt';
      GetMem(Attach, Size);
      //Get attach file to memory

      if GetAttach(MailboxHandle, Folder.Index, ListView1.Selected.Index,
        AttachProp.Number, Attach) = OMS_OK then
      begin

        //Save attach from memory to file
        AttachMemoryStream := TMemoryStream.Create;
        AttachMemoryStream.Write(Attach^, Size);
        AttachMemoryStream.Position := 0;
        AttachMemoryStream.SaveToFile(ExtractFileDir(ParamStr(0)) +
         '\temporary\' + FileName);
        AttachMemoryStream.Free;

        ShellExecute(Handle, '', PChar(ExtractFileDir(ParamStr(0)) +
         '\temporary\' + FileName), 0, 0, SW_Normal);

      end;
      FreeMem(Attach);
    end;