Table of Contents

Folders and messages

Once connected, TTMSFNCCloudMicrosoftOutlookMail reads the account's mail folders and the messages inside them. Every request is asynchronous — a method returns immediately and the result arrives in a matching On... event, with the retrieved data exposed through a collection property on the component. This chapter covers listing folders, retrieving messages page by page, and the fields available on a retrieved message.

The async result model

No mail operation blocks waiting for the network. Check ARequestResult.Success first, and read ARequestResult.ResultString for the raw response or error detail on failure. The retrieved data itself is not passed as an event parameter — read it from the component's Folders or Mails collection once the event fires.

Listing mail folders

GetFolders retrieves the account's mail folders, paged with APageSize and APageIndex, and raises OnGetFolders when the page is available; read the result from Folders.

procedure TForm1.ListMailFolders;
begin
  TMSFNCCloudMicrosoftOutlookMail1.OnGetFolders := OutlookMailFoldersListed;
  TMSFNCCloudMicrosoftOutlookMail1.GetFolders(25, 0); // first 25 folders
end;

procedure TForm1.OutlookMailFoldersListed(Sender: TObject;
  const ARequestResult: TTMSFNCCloudBaseRequestResult);
var
  i: Integer;
begin
  if not ARequestResult.Success then
    Exit;

  for i := 0 to TMSFNCCloudMicrosoftOutlookMail1.Folders.Count - 1 do
    Memo1.Lines.Add(TMSFNCCloudMicrosoftOutlookMail1.Folders[i].DisplayName
      + ' (' + IntToStr(TMSFNCCloudMicrosoftOutlookMail1.Folders[i].ItemCount) + ')');
end;

Retrieving messages

GetMails retrieves messages from a folder ('Inbox' by default), also paged with APageSize and APageIndex, raising OnGetMails; read the result from Mails. Each retrieved TTMSFNCCloudMicrosoftOutlookMailItem exposes the subject, body, sender and recipients, and metadata such as Importance, IsRead, IsDraft, HasAttachments, ConversationID and a WebLink that opens the message in the Outlook web client.

procedure TForm1.ListInboxMessages;
begin
  TMSFNCCloudMicrosoftOutlookMail1.OnGetMails := OutlookMailMessagesListed;
  TMSFNCCloudMicrosoftOutlookMail1.GetMails('Inbox', 50, 0); // first 50 messages
end;

procedure TForm1.OutlookMailMessagesListed(Sender: TObject;
  const ARequestResult: TTMSFNCCloudBaseRequestResult);
var
  i: Integer;
  m: TTMSFNCCloudMicrosoftOutlookMailItem;
begin
  if not ARequestResult.Success then
    Exit;

  for i := 0 to TMSFNCCloudMicrosoftOutlookMail1.Mails.Count - 1 do
  begin
    m := TMSFNCCloudMicrosoftOutlookMail1.Mails[i];
    if m.HasAttachments then
      Memo1.Lines.Add(m.Subject + ' - ' + m.FromEmail + ' [has attachments]')
    else
      Memo1.Lines.Add(m.Subject + ' - ' + m.FromEmail);
  end;
end;

Combining a folder listing with a message page

Listing the folders first lets you resolve a folder ID before paging through its messages — here the folders are listed, and the first non-default folder found is used to retrieve its first page of messages:

procedure TForm1.BrowseFoldersThenMessages;
begin
  TMSFNCCloudMicrosoftOutlookMail1.OnGetFolders := ListedThenGetMails;
  TMSFNCCloudMicrosoftOutlookMail1.OnGetMails := OutlookMailFolderMessagesListed;
  TMSFNCCloudMicrosoftOutlookMail1.GetFolders(25, 0);
end;

procedure TForm1.ListedThenGetMails(Sender: TObject;
  const ARequestResult: TTMSFNCCloudBaseRequestResult);
var
  i: Integer;
begin
  if not ARequestResult.Success then
    Exit;

  for i := 0 to TMSFNCCloudMicrosoftOutlookMail1.Folders.Count - 1 do
  begin
    if TMSFNCCloudMicrosoftOutlookMail1.Folders[i].DisplayName <> 'Inbox' then
    begin
      TMSFNCCloudMicrosoftOutlookMail1.GetMails(TMSFNCCloudMicrosoftOutlookMail1.Folders[i].ID, 25, 0);
      Break;
    end;
  end;
end;

procedure TForm1.OutlookMailFolderMessagesListed(Sender: TObject;
  const ARequestResult: TTMSFNCCloudBaseRequestResult);
var
  i: Integer;
begin
  if ARequestResult.Success then
    for i := 0 to TMSFNCCloudMicrosoftOutlookMail1.Mails.Count - 1 do
      Memo1.Lines.Add(TMSFNCCloudMicrosoftOutlookMail1.Mails[i].Subject);
end;

Common mistakes

  • Reading Folders/Mails before the event fires. The collection is only populated once OnGetFolders / OnGetMails reports success; reading it immediately after calling GetFolders / GetMails sees stale or empty data.
  • Assuming one page is the whole mailbox. GetMails returns at most APageSize messages; increment APageIndex to page through a folder with more messages than that.

See also