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

Visual FoxPro
LOCAL lnSuccess
LOCAL loStatusText
LOCAL loStatusMatch
LOCAL lnCompleted
LOCAL loToken
LOCAL lcMailbox
LOCAL loImap
LOCAL lcCapabilities
LOCAL loFolders
LOCAL lcAllMail
LOCAL lnFolderMatches
LOCAL f
LOCAL loMailboxNames
LOCAL loUnique
LOCAL loFound
LOCAL loUidStrings
LOCAL loRaw
LOCAL loCaptures
LOCAL lnFolderIndex
LOCAL lcSelected
LOCAL i
LOCAL lcUid
LOCAL loJoined1
LOCAL lcResponse
LOCAL loJoined2
LOCAL lcPattern
LOCAL lnCount
LOCAL lcMessageId
LOCAL lcThreadId

lnSuccess = 0

*  Assumes Chilkat is unlocked. See Global Unlock Sample.

loStatusText = CreateObject('Chilkat.StringBuilder')
loStatusMatch = CreateObject('Chilkat.JsonObject')

loToken = CreateObject('Chilkat.JsonObject')
lnSuccess = loToken.LoadFile("gmail-mail-token.json")
IF (lnSuccess <> 1) THEN
    ? "Could not load the protocol token from the private working directory."
    RELEASE loStatusText
    RELEASE loStatusMatch
    RELEASE loToken
    CANCEL
ENDIF

IF ((loToken.JsonTypeOf("access_token") <> 1) OR (loToken.StringOfEquals("access_token","",1) = 1)) THEN
    ? "Authorize or refresh the mailbox first."
    RELEASE loStatusText
    RELEASE loStatusMatch
    RELEASE loToken
    CANCEL
ENDIF

lcMailbox = "user@example.com"
loImap = CreateObject('Chilkat.Imap')
loImap.Ssl = 1
loImap.Port = 993
loImap.RequireSslCertVerify = 1
loImap.AuthMethod = "XOAUTH2"
lnSuccess = loImap.Connect("imap.gmail.com")
IF (lnSuccess <> 1) THEN
    ? "Could not establish the Gmail IMAP TLS connection."
    RELEASE loStatusText
    RELEASE loStatusMatch
    RELEASE loToken
    RELEASE loImap
    CANCEL
ENDIF

lnSuccess = loImap.Login(lcMailbox,loToken.StringOf("access_token"))
IF (lnSuccess <> 1) THEN
    loImap.Disconnect()
    ? "IMAP authentication failed. Check the mailbox, scope, expiry, and account policy."
    RELEASE loStatusText
    RELEASE loStatusMatch
    RELEASE loToken
    RELEASE loImap
    CANCEL
ENDIF

lcCapabilities = loImap.Capability()
IF ((loImap.LastMethodSuccess <> 1) OR (loImap.HasCapability("X-GM-EXT-1",lcCapabilities) <> 1)) THEN
    loImap.Logout()
    loImap.Disconnect()
    ? "Gmail IMAP extensions are unavailable."
    RELEASE loStatusText
    RELEASE loStatusMatch
    RELEASE loToken
    RELEASE loImap
    CANCEL
ENDIF

loFolders = CreateObject('Chilkat.Mailboxes')
lnSuccess = loImap.MbxList(0,"","*",loFolders)
IF (lnSuccess <> 1) THEN
    loImap.Logout()
    loImap.Disconnect()
    ? "Could not list Gmail folders."
    RELEASE loStatusText
    RELEASE loStatusMatch
    RELEASE loToken
    RELEASE loImap
    RELEASE loFolders
    CANCEL
ENDIF

lcAllMail = ""
lnFolderMatches = 0
f = 0
DO WHILE (f < loFolders.Count)
    IF ((loFolders.HasFlag(f,"\All") = 1) AND (loFolders.IsSelectable(f) = 1)) THEN
        lcAllMail = loFolders.GetName(f)
        lnFolderMatches = lnFolderMatches + 1
    ENDIF

    f = f + 1
ENDDO
IF (lnFolderMatches <> 1) THEN
    loImap.Logout()
    loImap.Disconnect()
    ? "Expected one selectable folder with the \All special-use attribute. Check label visibility."
    RELEASE loStatusText
    RELEASE loStatusMatch
    RELEASE loToken
    RELEASE loImap
    RELEASE loFolders
    CANCEL
ENDIF

loMailboxNames = CreateObject('Chilkat.StringTable')
loMailboxNames.Append("INBOX")
loMailboxNames.Append(lcAllMail)
loUnique = CreateObject('Chilkat.JsonObject')
loFound = CreateObject('Chilkat.MessageSet')
loUidStrings = CreateObject('Chilkat.StringTable')
loRaw = CreateObject('Chilkat.StringBuilder')
loCaptures = CreateObject('Chilkat.JsonObject')
lnFolderIndex = 0
DO WHILE (lnFolderIndex < loMailboxNames.Count)
    lcSelected = loMailboxNames.StringAt(lnFolderIndex)
    lnSuccess = loImap.ExamineMailbox(lcSelected)
    IF (lnSuccess <> 1) THEN
        loImap.Logout()
        loImap.Disconnect()
        ? "Could not open the mailbox read-only."
        RELEASE loStatusText
        RELEASE loStatusMatch
        RELEASE loToken
        RELEASE loImap
        RELEASE loFolders
        RELEASE loMailboxNames
        RELEASE loUnique
        RELEASE loFound
        RELEASE loUidStrings
        RELEASE loRaw
        RELEASE loCaptures
        CANCEL
    ENDIF

    lnSuccess = loImap.QueryMbx("ALL",1,loFound)
    IF (lnSuccess <> 1) THEN
        loImap.Logout()
        loImap.Disconnect()
        ? "Could not obtain message UIDs."
        RELEASE loStatusText
        RELEASE loStatusMatch
        RELEASE loToken
        RELEASE loImap
        RELEASE loFolders
        RELEASE loMailboxNames
        RELEASE loUnique
        RELEASE loFound
        RELEASE loUidStrings
        RELEASE loRaw
        RELEASE loCaptures
        CANCEL
    ENDIF

    loUidStrings.Clear()
    IF (loFound.Count > 0) THEN
        loUidStrings.SplitAndAppend(loFound.ToCommaSeparatedStr(),",",0,0)
    ENDIF

    *  Sample up to 10 messages from each mailbox; this is not a complete synchronization.
    i = 0
    DO WHILE ((i < loUidStrings.Count) AND (i < 10))
        lcUid = loUidStrings.StringAt(i)
        loJoined1 = CreateObject('Chilkat.StringBuilder')
        loJoined1.Append("UID FETCH ")
        loJoined1.Append(lcUid)
        loJoined1.Append(" (UID X-GM-MSGID X-GM-THRID)")
        lcResponse = loImap.SendRawCommand(loJoined1.GetAsString())
        loStatusText.SetString(lcResponse)
        *  A completed raw exchange can still return NO or BAD. Require tagged OK.
        lnCompleted = loStatusText.RegexMatch("(?i)(?:\A|\r\n)[^*+ \r\n]+ OK[^\r\n]*\r?\n?\z",loStatusMatch,1000)

        IF ((loImap.LastMethodSuccess <> 1) OR (lnCompleted <> 1)) THEN
            loImap.Logout()
            loImap.Disconnect()
            ? "Could not fetch Gmail IDs."
            RELEASE loStatusText
            RELEASE loStatusMatch
            RELEASE loToken
            RELEASE loImap
            RELEASE loFolders
            RELEASE loMailboxNames
            RELEASE loUnique
            RELEASE loFound
            RELEASE loUidStrings
            RELEASE loRaw
            RELEASE loCaptures
            RELEASE loJoined1
            CANCEL
        ENDIF

        loRaw.SetString(lcResponse)
        *  Match only this UID's metadata line. Attribute order need not be fixed.
        *  Unsolicited EXISTS/EXPUNGE/FLAGS lines do not match these three attributes.
        loJoined2 = CreateObject('Chilkat.StringBuilder')
        loJoined2.Append("(?mi)^\* [0-9]+ FETCH \((?=[^\r\n]*\bUID ")
        loJoined2.Append(lcUid)
        loJoined2.Append("(?: |\)))(?=[^\r\n]*\bX-GM-MSGID ([0-9]+)(?: |\)))(?=[^\r\n]*\bX-GM-THRID ([0-9]+)(?: |\)))[^\r\n]*\)\r?$")
        lcPattern = loJoined2.GetAsString()
        lnCount = loRaw.RegexMatch(lcPattern,loCaptures,1000)
        IF (lnCount < 0) THEN
            loImap.Logout()
            loImap.Disconnect()
            ? "Could not parse the Gmail metadata response."
            RELEASE loStatusText
            RELEASE loStatusMatch
            RELEASE loToken
            RELEASE loImap
            RELEASE loFolders
            RELEASE loMailboxNames
            RELEASE loUnique
            RELEASE loFound
            RELEASE loUidStrings
            RELEASE loRaw
            RELEASE loCaptures
            RELEASE loJoined1
            RELEASE loJoined2
            CANCEL
        ENDIF

        IF (lnCount = 1) THEN
            lcMessageId = loCaptures.StringOf("match[0].group[1].cap")
            lcThreadId = loCaptures.StringOf("match[0].group[2].cap")
            IF (loUnique.IndexOf(lcMessageId) < 0) THEN
                *  Direct JSON member names; both IDs remain strings without numeric conversion.
                loUnique.AppendString(lcMessageId,lcThreadId)
                ? "Message ID: " + lcMessageId + "  Thread ID: " + lcThreadId
            ELSE
                ? "Already encountered under another label: " + lcMessageId
            ENDIF

        ELSE
            ? "No single metadata row for UID " + lcUid + "; it may have disappeared. Skipping."
        ENDIF

        i = i + 1
    ENDDO
    lnFolderIndex = lnFolderIndex + 1
ENDDO
loImap.Logout()
loImap.Disconnect()
? "Unique sampled messages: " + STR(loUnique.Size)

RELEASE loStatusText
RELEASE loStatusMatch
RELEASE loToken
RELEASE loImap
RELEASE loFolders
RELEASE loMailboxNames
RELEASE loUnique
RELEASE loFound
RELEASE loUidStrings
RELEASE loRaw
RELEASE loCaptures
RELEASE loJoined1
RELEASE loJoined2