Sample code for 30+ languages & platforms
AutoIt Requires Chilkat v11.0.0+

Synchronize Gmail message IDs and labels between runs

See more GMail REST API Examples

Maintain gmail-sync.json containing the mailbox address, a string historyId, and a small local cache of message IDs, thread IDs, and labels. The first run scans the complete mailbox including Spam and Trash. Later runs follow all history pages and refresh only messages affected by additions, deletions, or label changes. A message GET returning 404 removes that message from the local cache.

An expired history checkpoint causes a full rebuild. The full scan records a checkpoint before listing messages, so the next run also reconciles changes made during the scan. Incremental runs save the final history response checkpoint only after every affected message has been processed. The cache and checkpoint are committed together, with a previous-file recovery path. History IDs remain strings throughout.

Run in a private directory and serialize runs sharing the cache. The sample holds the cache in memory for clarity. Larger applications can use database upserts and deletions, committing the checkpoint in the same transaction. The cache contains message identifiers and labels. Fetch MIME or selected headers when the application needs message content.

Authorize the application with https://www.googleapis.com/auth/gmail.readonly. The example reads the access token from gmail-token.json in a private working directory. Authorize a desktop application.

Google documentation

Chilkat AutoIt Downloads

AutoIt
Local $bSuccess = False

;  Assumes Chilkat is unlocked. See Global Unlock Sample.

$oToken = ObjCreate("Chilkat.JsonObject")
$bSuccess = $oToken.LoadFile("gmail-token.json")
If ($bSuccess <> True) Then
    ConsoleWrite("Could not read gmail-token.json from the private working directory." & @CRLF)
    Exit
EndIf

If (($oToken.JsonTypeOf("access_token") <> 1) Or ($oToken.StringOfEquals("access_token","",True) = True)) Then
    ConsoleWrite("An OAuth access token is required." & @CRLF)
    Exit
EndIf

$oHttp = ObjCreate("Chilkat.Http")
$oHttp.RequireSslCertVerify = True
$oHttp.AuthToken = $oToken.StringOf("access_token")
$oResp = ObjCreate("Chilkat.HttpResponse")
$oReply = ObjCreate("Chilkat.JsonObject")
$oFiles = ObjCreate("Chilkat.FileAccess")
;  Recover the previous complete file if a run stopped during replacement.
Local $iFileStatus = $oFiles.FileExists3("gmail-sync.json")
If ($iFileStatus < 0) Then
    ConsoleWrite("Could not inspect gmail-sync.json." & @CRLF)
    Exit
EndIf

If ($iFileStatus = 0) Then
Local $iBackupStatus = $oFiles.FileExists3("gmail-sync.json.previous")
    If ($iBackupStatus < 0) Then
        ConsoleWrite("Could not inspect the backup file." & @CRLF)
        Exit
    EndIf

    If ($iBackupStatus = 1) Then
        $bSuccess = $oFiles.FileRename("gmail-sync.json.previous","gmail-sync.json")
        If ($bSuccess <> True) Then
            ConsoleWrite("Could not restore the previous complete file." & @CRLF)
            Exit
        EndIf

        $iFileStatus = 1
    EndIf

EndIf

$oState = ObjCreate("Chilkat.JsonObject")
If ($iFileStatus = 1) Then
    $bSuccess = $oState.LoadFile("gmail-sync.json")
    If ($bSuccess <> True) Then
        ConsoleWrite("Could not read the existing synchronization state." & @CRLF)
        Exit
    EndIf

    If (($oState.JsonTypeOf("historyId") <> 1) Or ($oState.JsonTypeOf("messages") <> 3) Or ($oState.JsonTypeOf("emailAddress") <> 1)) Then
        ConsoleWrite("The synchronization state is incomplete. Restore its previous complete copy." & @CRLF)
        Exit
    EndIf

EndIf

$bSuccess = $oHttp.HttpNoBody("GET","https://gmail.googleapis.com/gmail/v1/users/me/profile",$oResp)
If ($oResp.StatusCode = 0) Then
    ConsoleWrite("Gmail did not return an HTTP response." & @CRLF)
    Exit
EndIf

If (($bSuccess <> True) Or ($oResp.StatusCode < 200) Or ($oResp.StatusCode >= 300)) Then
    ConsoleWrite("Gmail HTTP " & $oResp.StatusCode & @CRLF)
    $bSuccess = $oReply.Load($oResp.BodyStr)
    If ($bSuccess = True) Then
        ConsoleWrite($oReply.StringOf("error.message") & @CRLF)
    EndIf

    Exit
EndIf

$bSuccess = $oReply.Load($oResp.BodyStr)
If ($bSuccess <> True) Then
    ConsoleWrite("Expected a Gmail JSON response." & @CRLF)
    Exit
EndIf

If (($oReply.JsonTypeOf("emailAddress") <> 1) Or ($oReply.StringOfEquals("emailAddress","",True) = True)) Then
    ConsoleWrite("Expected emailAddress in the response." & @CRLF)
    Exit
EndIf

If (($oReply.JsonTypeOf("historyId") <> 1) Or ($oReply.StringOfEquals("historyId","",True) = True)) Then
    ConsoleWrite("Expected historyId in the response." & @CRLF)
    Exit
EndIf

Local $sMailbox = $oReply.StringOf("emailAddress")
Local $sBaseline = $oReply.StringOf("historyId")
If ($iFileStatus = 1) Then
    If ($oState.StringOfEquals("emailAddress",$sMailbox,False) <> True) Then
        ConsoleWrite("Use a separate synchronization file for this mailbox." & @CRLF)
        Exit
    EndIf

EndIf

Local $bFullSync = $iFileStatus = 0
Local $sCheckpoint = $sBaseline
$oIds = ObjCreate("Chilkat.StringArray")
$oIds.Unique = True
$oBaseUrl = ObjCreate("Chilkat.StringBuilder")
$oUrl = ObjCreate("Chilkat.StringBuilder")
Local $sPageToken = ""
Local $bMore = True

If ($bFullSync <> True) Then
    $oBaseUrl.SetString("https://gmail.googleapis.com/gmail/v1/users/me/history?maxResults=500&startHistoryId=")
    $oBaseUrl.Append($oHttp.UrlEncode($oState.StringOf("historyId")))
    $oChangeTypes = ObjCreate("Chilkat.StringTable")
    $bSuccess = $oChangeTypes.Append("messagesAdded")
    If ($bSuccess <> True) Then
        ConsoleWrite($oChangeTypes.LastErrorText & @CRLF)
        Exit
    EndIf

    $bSuccess = $oChangeTypes.Append("messagesDeleted")
    If ($bSuccess <> True) Then
        ConsoleWrite($oChangeTypes.LastErrorText & @CRLF)
        Exit
    EndIf

    $bSuccess = $oChangeTypes.Append("labelsAdded")
    If ($bSuccess <> True) Then
        ConsoleWrite($oChangeTypes.LastErrorText & @CRLF)
        Exit
    EndIf

    $bSuccess = $oChangeTypes.Append("labelsRemoved")
    If ($bSuccess <> True) Then
        ConsoleWrite($oChangeTypes.LastErrorText & @CRLF)
        Exit
    EndIf

    $oRecord = ObjCreate("Chilkat.JsonObject")
    $oEventPath = ObjCreate("Chilkat.StringBuilder")
    While ($bMore = True)
        $oUrl.SetString($oBaseUrl.GetAsString())
        $oUrl.Append("&pageToken=")
        $oUrl.Append($oHttp.UrlEncode($sPageToken))
        $bSuccess = $oHttp.HttpNoBody("GET",$oUrl.GetAsString(),$oResp)
        If ($oResp.StatusCode = 404) Then
            ConsoleWrite("History checkpoint expired. Rebuilding the cache." & @CRLF)
            $bFullSync = True
            $bMore = False
        Else
            If ($oResp.StatusCode = 0) Then
                ConsoleWrite("Gmail did not return an HTTP response." & @CRLF)
                Exit
            EndIf

            If (($bSuccess <> True) Or ($oResp.StatusCode < 200) Or ($oResp.StatusCode >= 300)) Then
                ConsoleWrite("Gmail HTTP " & $oResp.StatusCode & @CRLF)
                $bSuccess = $oReply.Load($oResp.BodyStr)
                If ($bSuccess = True) Then
                    ConsoleWrite($oReply.StringOf("error.message") & @CRLF)
                EndIf

                Exit
            EndIf

            $bSuccess = $oReply.Load($oResp.BodyStr)
            If ($bSuccess <> True) Then
                ConsoleWrite("Expected a Gmail JSON response." & @CRLF)
                Exit
            EndIf

Local $iH = 0
            While ($iH < $oReply.SizeOfArray("history"))
                $oReply.I = $iH
                $bSuccess = $oReply.ObjectOf2("history[i]",$oRecord)
                If ($bSuccess <> True) Then
                    ConsoleWrite($oReply.LastErrorText & @CRLF)
                    Exit
                EndIf

Local $iT = 0
                While ($iT < $oChangeTypes.Count)
Local $iJ = 0
                    While ($iJ < $oRecord.SizeOfArray($oChangeTypes.StringAt($iT)))
                        $oEventPath.SetString($oChangeTypes.StringAt($iT))
                        $oEventPath.Append("[")
                        $oEventPath.AppendInt($iJ)
                        $oEventPath.Append("].message.id")
                        $bSuccess = $oIds.Append($oRecord.StringOf($oEventPath.GetAsString()))
                        If ($bSuccess <> True) Then
                            ConsoleWrite($oIds.LastErrorText & @CRLF)
                            Exit
                        EndIf

                        $iJ = $iJ + 1
                    Wend
                    $iT = $iT + 1
                Wend
                $iH = $iH + 1
            Wend
            $sPageToken = ""
            If ($oReply.JsonTypeOf("nextPageToken") = 1) Then
                $sPageToken = $oReply.StringOf("nextPageToken")
            EndIf

            $bMore = $sPageToken <> ""
            If ($bMore <> True) Then
                If (($oReply.JsonTypeOf("historyId") <> 1) Or ($oReply.StringOfEquals("historyId","",True) = True)) Then
                    ConsoleWrite("Expected historyId in the response." & @CRLF)
                    Exit
                EndIf

                $sCheckpoint = $oReply.StringOf("historyId")
            EndIf

        EndIf

    Wend
EndIf

If ($bFullSync = True) Then
    ;  Rebuild in memory. Any failure leaves the committed file available for a retry.
    $oIds.Clear 
    $oState.Clear 
    $bSuccess = $oState.UpdateString("emailAddress",$sMailbox)
    If ($bSuccess <> True) Then
        ConsoleWrite($oState.LastErrorText & @CRLF)
        Exit
    EndIf

    $bSuccess = $oState.UpdateNewObject("messages")
    If ($bSuccess <> True) Then
        ConsoleWrite($oState.LastErrorText & @CRLF)
        Exit
    EndIf

    $sCheckpoint = $sBaseline
    $sPageToken = ""
    $bMore = True
    While ($bMore = True)
        $oUrl.SetString("https://gmail.googleapis.com/gmail/v1/users/me/messages?maxResults=500&includeSpamTrash=true&pageToken=")
        $oUrl.Append($oHttp.UrlEncode($sPageToken))
        $bSuccess = $oHttp.HttpNoBody("GET",$oUrl.GetAsString(),$oResp)
        If ($oResp.StatusCode = 0) Then
            ConsoleWrite("Gmail did not return an HTTP response." & @CRLF)
            Exit
        EndIf

        If (($bSuccess <> True) Or ($oResp.StatusCode < 200) Or ($oResp.StatusCode >= 300)) Then
            ConsoleWrite("Gmail HTTP " & $oResp.StatusCode & @CRLF)
            $bSuccess = $oReply.Load($oResp.BodyStr)
            If ($bSuccess = True) Then
                ConsoleWrite($oReply.StringOf("error.message") & @CRLF)
            EndIf

            Exit
        EndIf

        $bSuccess = $oReply.Load($oResp.BodyStr)
        If ($bSuccess <> True) Then
            ConsoleWrite("Expected a Gmail JSON response." & @CRLF)
            Exit
        EndIf

Local $iM = 0
        While ($iM < $oReply.SizeOfArray("messages"))
            $oReply.I = $iM
            $bSuccess = $oIds.Append($oReply.StringOf("messages[i].id"))
            If ($bSuccess <> True) Then
                ConsoleWrite($oIds.LastErrorText & @CRLF)
                Exit
            EndIf

            $iM = $iM + 1
        Wend
        $sPageToken = ""
        If ($oReply.JsonTypeOf("nextPageToken") = 1) Then
            $sPageToken = $oReply.StringOf("nextPageToken")
        EndIf

        $bMore = $sPageToken <> ""
    Wend
EndIf

$oMessages = ObjCreate("Chilkat.JsonObject")
$bSuccess = $oState.ObjectOf2("messages",$oMessages)
If ($bSuccess <> True) Then
    ConsoleWrite($oState.LastErrorText & @CRLF)
    Exit
EndIf

$oCachedMessage = ObjCreate("Chilkat.JsonObject")
Local $i = 0
While ($i < $oIds.Count)
Local $sMessageId = $oIds.GetString($i)
    $oUrl.SetString("https://gmail.googleapis.com/gmail/v1/users/me/messages/")
    $oUrl.Append($oHttp.UrlEncode($sMessageId))
    $oUrl.Append("?format=minimal&fields=id,threadId,labelIds")
    $bSuccess = $oHttp.HttpNoBody("GET",$oUrl.GetAsString(),$oResp)
    If ($oResp.StatusCode = 404) Then
        If ($oMessages.HasMember($sMessageId) = True) Then
            $bSuccess = $oMessages.Delete($sMessageId)
            If ($bSuccess <> True) Then
                ConsoleWrite($oMessages.LastErrorText & @CRLF)
                Exit
            EndIf

        EndIf

        ConsoleWrite("Removed from cache: " & $sMessageId & @CRLF)
    Else
        If ($oResp.StatusCode = 0) Then
            ConsoleWrite("Gmail did not return an HTTP response." & @CRLF)
            Exit
        EndIf

        If (($bSuccess <> True) Or ($oResp.StatusCode < 200) Or ($oResp.StatusCode >= 300)) Then
            ConsoleWrite("Gmail HTTP " & $oResp.StatusCode & @CRLF)
            $bSuccess = $oReply.Load($oResp.BodyStr)
            If ($bSuccess = True) Then
                ConsoleWrite($oReply.StringOf("error.message") & @CRLF)
            EndIf

            Exit
        EndIf

        $bSuccess = $oReply.Load($oResp.BodyStr)
        If ($bSuccess <> True) Then
            ConsoleWrite("Expected a Gmail JSON response." & @CRLF)
            Exit
        EndIf

        If ($oReply.StringOfEquals("id",$sMessageId,True) <> True) Then
            ConsoleWrite("Unexpected message ID in the response." & @CRLF)
            Exit
        EndIf

        $bSuccess = $oMessages.UpdateNewObject($sMessageId)
        If ($bSuccess <> True) Then
            ConsoleWrite($oMessages.LastErrorText & @CRLF)
            Exit
        EndIf

        $bSuccess = $oMessages.ObjectOf2($sMessageId,$oCachedMessage)
        If ($bSuccess <> True) Then
            ConsoleWrite($oMessages.LastErrorText & @CRLF)
            Exit
        EndIf

        $bSuccess = $oCachedMessage.Load($oReply.Emit())
        If ($bSuccess <> True) Then
            ConsoleWrite($oCachedMessage.LastErrorText & @CRLF)
            Exit
        EndIf

        ConsoleWrite("Cached message: " & $sMessageId & @CRLF)
    EndIf

    $i = $i + 1
Wend
$bSuccess = $oState.UpdateString("historyId",$sCheckpoint)
If ($bSuccess <> True) Then
    ConsoleWrite($oState.LastErrorText & @CRLF)
    Exit
EndIf

;  Prepare the complete replacement before moving the last committed file.
$bSuccess = $oState.WriteFile("gmail-sync.json.new")
If ($bSuccess <> True) Then
    ConsoleWrite("Could not write the replacement file." & @CRLF)
    Exit
EndIf

If ($oFiles.FileExists("gmail-sync.json") = True) Then
    If ($oFiles.FileExists("gmail-sync.json.previous") = True) Then
        $bSuccess = $oFiles.FileDelete("gmail-sync.json.previous")
        If ($bSuccess <> True) Then
            ConsoleWrite("Could not rotate the previous backup." & @CRLF)
            Exit
        EndIf

    EndIf

    $bSuccess = $oFiles.FileRename("gmail-sync.json","gmail-sync.json.previous")
    If ($bSuccess <> True) Then
        ConsoleWrite("Could not retain the previous complete file." & @CRLF)
        Exit
    EndIf

EndIf

$bSuccess = $oFiles.FileRename("gmail-sync.json.new","gmail-sync.json")
If ($bSuccess <> True) Then
    ConsoleWrite("Could not commit the replacement. The previous complete file is retained." & @CRLF)
    Exit
EndIf

ConsoleWrite("Synchronization committed. Cached messages: " & $oMessages.Size & @CRLF)
ConsoleWrite("Saved history ID: " & $sCheckpoint & @CRLF)