Sample code for 30+ languages & platforms
Delphi DLL Requires Chilkat v11.1.0+

Gmail IMAP: Discover Special Folders

See more GMail SMTP/IMAP/POP Examples

Find Gmail special folders from the attributes returned by LIST, using MbxList and Mailboxes.HasFlag. The result maps roles such as Sent and Trash to the server-provided mailbox names. Chilkat decodes mailbox names for use with its mailbox methods.

Folder names can be localized and visibility can differ by account. The role attributes are stable; do not hard-code [Gmail]/Sent Mail or use the deprecated XLIST command. INBOX is a protocol-defined name. Missing map keys indicate folders not advertised by the server.

Use the mailbox that authorized the full-mail scope https://mail.google.com/. Obtain the protocol OAuth token and refresh it before running this example. The token is loaded from gmail-mail-token.json in a private working directory; a narrow Gmail REST token is insufficient.

Google documentation

Chilkat Delphi DLL Downloads

Delphi DLL
var
success: Boolean;
token: HCkJsonObject;
mailbox: PWideChar;
imap: HCkImap;
folders: HCkMailboxes;
special: HCkJsonObject;
i: Integer;

begin
success := False;

//  Assumes Chilkat is unlocked. See Global Unlock Sample.

token := CkJsonObject_Create();
success := CkJsonObject_LoadFile(token,'gmail-mail-token.json');
if (success <> True) then
  begin
    Memo1.Lines.Add('Could not load the protocol token from the private working directory.');
    Exit;
  end;
if ((CkJsonObject_JsonTypeOf(token,'access_token') <> 1) or (CkJsonObject_StringOfEquals(token,'access_token','',True) = True)) then
  begin
    Memo1.Lines.Add('Authorize or refresh the mailbox first.');
    Exit;
  end;
mailbox := 'user@example.com';
imap := CkImap_Create();
CkImap_putSsl(imap,True);
CkImap_putPort(imap,993);
CkImap_putRequireSslCertVerify(imap,True);
CkImap_putAuthMethod(imap,'XOAUTH2');
success := CkImap_Connect(imap,'imap.gmail.com');
if (success <> True) then
  begin
    Memo1.Lines.Add('Could not establish the Gmail IMAP TLS connection.');
    Exit;
  end;
success := CkImap_Login(imap,mailbox,CkJsonObject__stringOf(token,'access_token'));
if (success <> True) then
  begin
    CkImap_Disconnect(imap);
    Memo1.Lines.Add('IMAP authentication failed. Check the mailbox, scope, expiry, and account policy.');
    Exit;
  end;
folders := CkMailboxes_Create();
success := CkImap_MbxList(imap,False,'','*',folders);
if (success <> True) then
  begin
    CkImap_Logout(imap);
    CkImap_Disconnect(imap);
    Memo1.Lines.Add('Could not list Gmail folders.');
    Exit;
  end;
//  LIST special-use attributes work with localized folder names. XLIST is obsolete.
special := CkJsonObject_Create();
i := 0;
while (i < CkMailboxes_getCount(folders)) do
  begin
    if (CkMailboxes_IsSelectable(folders,i) = True) then
      begin
        Memo1.Lines.Add(CkMailboxes__getName(folders,i) + '  ' + CkMailboxes__getFlags(folders,i));
        if (CkMailboxes_HasFlag(folders,i,'\All') = True) then
          begin
            CkJsonObject_UpdateString(special,'allMail',CkMailboxes__getName(folders,i));
          end;
        if (CkMailboxes_HasFlag(folders,i,'\Sent') = True) then
          begin
            CkJsonObject_UpdateString(special,'sent',CkMailboxes__getName(folders,i));
          end;
        if (CkMailboxes_HasFlag(folders,i,'\Drafts') = True) then
          begin
            CkJsonObject_UpdateString(special,'drafts',CkMailboxes__getName(folders,i));
          end;
        if (CkMailboxes_HasFlag(folders,i,'\Junk') = True) then
          begin
            CkJsonObject_UpdateString(special,'spam',CkMailboxes__getName(folders,i));
          end;
        if (CkMailboxes_HasFlag(folders,i,'\Trash') = True) then
          begin
            CkJsonObject_UpdateString(special,'trash',CkMailboxes__getName(folders,i));
          end;
        if (CkMailboxes_HasFlag(folders,i,'\Flagged') = True) then
          begin
            CkJsonObject_UpdateString(special,'starred',CkMailboxes__getName(folders,i));
          end;
        if (CkMailboxes_HasFlag(folders,i,'\Important') = True) then
          begin
            CkJsonObject_UpdateString(special,'important',CkMailboxes__getName(folders,i));
          end;
      end;
    i := i + 1;
  end;

CkImap_Logout(imap);
CkImap_Disconnect(imap);
CkJsonObject_putEmitCompact(special,False);
Memo1.Lines.Add(CkJsonObject__emit(special));
//  Missing keys mean the folder was not advertised. Do not substitute an English name.

CkJsonObject_Dispose(token);
CkImap_Dispose(imap);
CkMailboxes_Dispose(folders);
CkJsonObject_Dispose(special);