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.
Chilkat AutoIt Downloads
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)