Sample code for 30+ languages & platforms
Objective-C 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 Objective-C Downloads

Objective-C
#import <CkoStringBuilder.h>
#import <CkoJsonObject.h>
#import <NSString.h>
#import <CkoImap.h>
#import <CkoMailboxes.h>
#import <CkoStringTable.h>
#import <CkoMessageSet.h>

BOOL success = NO;

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

CkoStringBuilder *statusText = [[CkoStringBuilder alloc] init];
CkoJsonObject *statusMatch = [[CkoJsonObject alloc] init];
int completed;
CkoJsonObject *token = [[CkoJsonObject alloc] init];
success = [token LoadFile: @"gmail-mail-token.json"];
if (success != YES) {
    NSLog(@"%@",@"Could not load the protocol token from the private working directory.");
    return;
}

if (([[token JsonTypeOf: @"access_token"] intValue] != 1) || ([token StringOfEquals: @"access_token" value: @"" caseSensitive: YES] == YES)) {
    NSLog(@"%@",@"Authorize or refresh the mailbox first.");
    return;
}

NSString *mailbox = @"user@example.com";
CkoImap *imap = [[CkoImap alloc] init];
imap.Ssl = YES;
imap.Port = [NSNumber numberWithInt:993];
imap.RequireSslCertVerify = YES;
imap.AuthMethod = @"XOAUTH2";
success = [imap Connect: @"imap.gmail.com"];
if (success != YES) {
    NSLog(@"%@",@"Could not establish the Gmail IMAP TLS connection.");
    return;
}

success = [imap Login: mailbox password: [token StringOf: @"access_token"]];
if (success != YES) {
    [imap Disconnect];
    NSLog(@"%@",@"IMAP authentication failed. Check the mailbox, scope, expiry, and account policy.");
    return;
}

NSString *capabilities = [imap Capability];
if ((imap.LastMethodSuccess != YES) || ([imap HasCapability: @"X-GM-EXT-1" capabilityResponse: capabilities] != YES)) {
    [imap Logout];
    [imap Disconnect];
    NSLog(@"%@",@"Gmail IMAP extensions are unavailable.");
    return;
}

CkoMailboxes *folders = [[CkoMailboxes alloc] init];
success = [imap MbxList: NO reference: @"" mbxPattern: @"*" mboxes: folders];
if (success != YES) {
    [imap Logout];
    [imap Disconnect];
    NSLog(@"%@",@"Could not list Gmail folders.");
    return;
}

NSString *allMail = @"";
int folderMatches = 0;
int f = 0;
while ((f < [folders.Count intValue])) {
    if (([folders HasFlag: [NSNumber numberWithInt: f] flagName: @"\\All"] == YES) && ([folders IsSelectable: [NSNumber numberWithInt: f]] == YES)) {
        allMail = [folders GetName: [NSNumber numberWithInt: f]];
        folderMatches = folderMatches + 1;
    }

    f = f + 1;
}

if (folderMatches != 1) {
    [imap Logout];
    [imap Disconnect];
    NSLog(@"%@",@"Expected one selectable folder with the \\All special-use attribute. Check label visibility.");
    return;
}

CkoStringTable *mailboxNames = [[CkoStringTable alloc] init];
[mailboxNames Append: @"INBOX"];
[mailboxNames Append: allMail];
CkoJsonObject *unique = [[CkoJsonObject alloc] init];
CkoMessageSet *found = [[CkoMessageSet alloc] init];
CkoStringTable *uidStrings = [[CkoStringTable alloc] init];
CkoStringBuilder *raw = [[CkoStringBuilder alloc] init];
CkoJsonObject *captures = [[CkoJsonObject alloc] init];
int folderIndex = 0;
while ((folderIndex < [mailboxNames.Count intValue])) {
    NSString *selected = [mailboxNames StringAt: [NSNumber numberWithInt: folderIndex]];
    success = [imap ExamineMailbox: selected];
    if (success != YES) {
        [imap Logout];
        [imap Disconnect];
        NSLog(@"%@",@"Could not open the mailbox read-only.");
        return;
    }

    success = [imap QueryMbx: @"ALL" bUid: YES msgSet: found];
    if (success != YES) {
        [imap Logout];
        [imap Disconnect];
        NSLog(@"%@",@"Could not obtain message UIDs.");
        return;
    }

    [uidStrings Clear];
    if ([found.Count intValue] > 0) {
        [uidStrings SplitAndAppend: [found ToCommaSeparatedStr] delimiterChar: @"," exceptDoubleQuoted: NO exceptEscaped: NO];
    }

    //  Sample up to 10 messages from each mailbox; this is not a complete synchronization.
    int i = 0;
    while (((i < [uidStrings.Count intValue]) && (i < 10))) {
        NSString *uid = [uidStrings StringAt: [NSNumber numberWithInt: i]];
        CkoStringBuilder *joined1 = [[CkoStringBuilder alloc] init];
        [joined1 Append: @"UID FETCH "];
        [joined1 Append: uid];
        [joined1 Append: @" (UID X-GM-MSGID X-GM-THRID)"];
        NSString *response = [imap SendRawCommand: [joined1 GetAsString]];
        [statusText SetString: response];
        //  A completed raw exchange can still return NO or BAD. Require tagged OK.
        completed = [[statusText RegexMatch: @"(?i)(?:\\A|\\r\\n)[^*+ \\r\\n]+ OK[^\\r\\n]*\\r?\\n?\\z" json: statusMatch timeoutMs: [NSNumber numberWithInt: 1000]] intValue];

        if ((imap.LastMethodSuccess != YES) || (completed != 1)) {
            [imap Logout];
            [imap Disconnect];
            NSLog(@"%@",@"Could not fetch Gmail IDs.");
            return;
        }

        [raw SetString: 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.
        CkoStringBuilder *joined2 = [[CkoStringBuilder alloc] init];
        [joined2 Append: @"(?mi)^\\* [0-9]+ FETCH \\((?=[^\\r\\n]*\\bUID "];
        [joined2 Append: uid];
        [joined2 Append: @"(?: |\\)))(?=[^\\r\\n]*\\bX-GM-MSGID ([0-9]+)(?: |\\)))(?=[^\\r\\n]*\\bX-GM-THRID ([0-9]+)(?: |\\)))[^\\r\\n]*\\)\\r?$"];
        NSString *pattern = [joined2 GetAsString];
        int count = [[raw RegexMatch: pattern json: captures timeoutMs: [NSNumber numberWithInt: 1000]] intValue];
        if (count < 0) {
            [imap Logout];
            [imap Disconnect];
            NSLog(@"%@",@"Could not parse the Gmail metadata response.");
            return;
        }

        if (count == 1) {
            NSString *messageId = [captures StringOf: @"match[0].group[1].cap"];
            NSString *threadId = [captures StringOf: @"match[0].group[2].cap"];
            if ([[unique IndexOf: messageId] intValue] < 0) {
                //  Direct JSON member names; both IDs remain strings without numeric conversion.
                [unique AppendString: messageId value: threadId];
                NSLog(@"%@%@%@%@",@"Message ID: ",messageId,@"  Thread ID: ",threadId);
            }
            else {
                NSLog(@"%@%@",@"Already encountered under another label: ",messageId);
            }

        }
        else {
            NSLog(@"%@%@%@",@"No single metadata row for UID ",uid,@"; it may have disappeared. Skipping.");
        }

        i = i + 1;
    }

    folderIndex = folderIndex + 1;
}

[imap Logout];
[imap Disconnect];
NSLog(@"%@%d",@"Unique sampled messages: ",[unique.Size intValue]);