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

Gmail IMAP: Identify Messages and Threads Across Folders

See more GMail SMTP/IMAP/POP Examples

Sample INBOX and the discovered All Mail folder, fetch Gmail message and thread IDs, and deduplicate messages appearing in both. Each X-GM-MSGID maps to an X-GM-THRID; equal thread IDs group messages in a Gmail conversation.

All identifiers are strings. IMAP UIDs identify messages only within one mailbox and UIDVALIDITY. Gmail IDs identify messages across labels, while the RFC Message-ID header is a separate identifier. Gmail IMAP IDs are unsigned decimal values; Gmail REST uses the corresponding hexadecimal strings. Do not pass these decimal strings directly as REST IDs.

The example reads at most ten messages per folder. Its regular expression extracts only the requested numeric metadata from a single-line FETCH result, tolerating attribute order and unrelated notifications. It is not a general IMAP/MIME parser. A vanished message is skipped. No message body is downloaded or marked read.

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;
statusText: HCkStringBuilder;
statusMatch: HCkJsonObject;
completed: Integer;
token: HCkJsonObject;
mailbox: PWideChar;
imap: HCkImap;
capabilities: PWideChar;
folders: HCkMailboxes;
allMail: PWideChar;
folderMatches: Integer;
f: Integer;
mailboxNames: HCkStringTable;
unique: HCkJsonObject;
found: HCkMessageSet;
uidStrings: HCkStringTable;
raw: HCkStringBuilder;
captures: HCkJsonObject;
folderIndex: Integer;
selected: PWideChar;
i: Integer;
uid: PWideChar;
joined1: HCkStringBuilder;
response: PWideChar;
joined2: HCkStringBuilder;
pattern: PWideChar;
count: Integer;
messageId: PWideChar;
threadId: PWideChar;

begin
success := False;

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

statusText := CkStringBuilder_Create();
statusMatch := CkJsonObject_Create();

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;
capabilities := CkImap__capability(imap);
if ((CkImap_getLastMethodSuccess(imap) <> True) or (CkImap_HasCapability(imap,'X-GM-EXT-1',capabilities) <> True)) then
  begin
    CkImap_Logout(imap);
    CkImap_Disconnect(imap);
    Memo1.Lines.Add('Gmail IMAP extensions are unavailable.');
    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;
allMail := '';
folderMatches := 0;
f := 0;
while (f < CkMailboxes_getCount(folders)) do
  begin
    if ((CkMailboxes_HasFlag(folders,f,'\All') = True) and (CkMailboxes_IsSelectable(folders,f) = True)) then
      begin
        allMail := CkMailboxes__getName(folders,f);
        folderMatches := folderMatches + 1;
      end;
    f := f + 1;
  end;

if (folderMatches <> 1) then
  begin
    CkImap_Logout(imap);
    CkImap_Disconnect(imap);
    Memo1.Lines.Add('Expected one selectable folder with the \All special-use attribute. Check label visibility.');
    Exit;
  end;
mailboxNames := CkStringTable_Create();
CkStringTable_Append(mailboxNames,'INBOX');
CkStringTable_Append(mailboxNames,allMail);
unique := CkJsonObject_Create();
found := CkMessageSet_Create();
uidStrings := CkStringTable_Create();
raw := CkStringBuilder_Create();
captures := CkJsonObject_Create();
folderIndex := 0;
while (folderIndex < CkStringTable_getCount(mailboxNames)) do
  begin
    selected := CkStringTable__stringAt(mailboxNames,folderIndex);
    success := CkImap_ExamineMailbox(imap,selected);
    if (success <> True) then
      begin
        CkImap_Logout(imap);
        CkImap_Disconnect(imap);
        Memo1.Lines.Add('Could not open the mailbox read-only.');
        Exit;
      end;
    success := CkImap_QueryMbx(imap,'ALL',True,found);
    if (success <> True) then
      begin
        CkImap_Logout(imap);
        CkImap_Disconnect(imap);
        Memo1.Lines.Add('Could not obtain message UIDs.');
        Exit;
      end;
    CkStringTable_Clear(uidStrings);
    if (CkMessageSet_getCount(found) > 0) then
      begin
        CkStringTable_SplitAndAppend(uidStrings,CkMessageSet__toCommaSeparatedStr(found),',',False,False);
      end;
    //  Sample up to 10 messages from each mailbox; this is not a complete synchronization.
    i := 0;
    while ((i < CkStringTable_getCount(uidStrings)) and (i < 10)) do
      begin
        uid := CkStringTable__stringAt(uidStrings,i);
        joined1 := CkStringBuilder_Create();
        CkStringBuilder_Append(joined1,'UID FETCH ');
        CkStringBuilder_Append(joined1,uid);
        CkStringBuilder_Append(joined1,' (UID X-GM-MSGID X-GM-THRID)');
        response := CkImap__sendRawCommand(imap,CkStringBuilder__getAsString(joined1));
        CkStringBuilder_SetString(statusText,response);
        //  A completed raw exchange can still return NO or BAD. Require tagged OK.
        completed := CkStringBuilder_RegexMatch(statusText,'(?i)(?:\A|\r\n)[^*+ \r\n]+ OK[^\r\n]*\r?\n?\z',statusMatch,1000);

        if ((CkImap_getLastMethodSuccess(imap) <> True) or (completed <> 1)) then
          begin
            CkImap_Logout(imap);
            CkImap_Disconnect(imap);
            Memo1.Lines.Add('Could not fetch Gmail IDs.');
            Exit;
          end;
        CkStringBuilder_SetString(raw,response);
        //  Match only this UID's metadata line. Attribute order need not be fixed.
        //  Unsolicited EXISTS/EXPUNGE/FLAGS lines do not match these three attributes.
        joined2 := CkStringBuilder_Create();
        CkStringBuilder_Append(joined2,'(?mi)^\* [0-9]+ FETCH \((?=[^\r\n]*\bUID ');
        CkStringBuilder_Append(joined2,uid);
        CkStringBuilder_Append(joined2,'(?: |\)))(?=[^\r\n]*\bX-GM-MSGID ([0-9]+)(?: |\)))(?=[^\r\n]*\bX-GM-THRID ([0-9]+)(?: |\)))[^\r\n]*\)\r?$');
        pattern := CkStringBuilder__getAsString(joined2);
        count := CkStringBuilder_RegexMatch(raw,pattern,captures,1000);
        if (count < 0) then
          begin
            CkImap_Logout(imap);
            CkImap_Disconnect(imap);
            Memo1.Lines.Add('Could not parse the Gmail metadata response.');
            Exit;
          end;
        if (count = 1) then
          begin
            messageId := CkJsonObject__stringOf(captures,'match[0].group[1].cap');
            threadId := CkJsonObject__stringOf(captures,'match[0].group[2].cap');
            if (CkJsonObject_IndexOf(unique,messageId) < 0) then
              begin
                //  Direct JSON member names; both IDs remain strings without numeric conversion.
                CkJsonObject_AppendString(unique,messageId,threadId);
                Memo1.Lines.Add('Message ID: ' + messageId + '  Thread ID: ' + threadId);
              end
            else
              begin
                Memo1.Lines.Add('Already encountered under another label: ' + messageId);
              end;
          end
        else
          begin
            Memo1.Lines.Add('No single metadata row for UID ' + uid + '; it may have disappeared. Skipping.');
          end;
        i := i + 1;
      end;

    folderIndex := folderIndex + 1;
  end;

CkImap_Logout(imap);
CkImap_Disconnect(imap);
Memo1.Lines.Add('Unique sampled messages: ' + IntToStr(CkJsonObject_getSize(unique)));

CkStringBuilder_Dispose(statusText);
CkJsonObject_Dispose(statusMatch);
CkJsonObject_Dispose(token);
CkImap_Dispose(imap);
CkMailboxes_Dispose(folders);
CkStringTable_Dispose(mailboxNames);
CkJsonObject_Dispose(unique);
CkMessageSet_Dispose(found);
CkStringTable_Dispose(uidStrings);
CkStringBuilder_Dispose(raw);
CkJsonObject_Dispose(captures);
        CkStringBuilder_Dispose(joined1);
        CkStringBuilder_Dispose(joined2);