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

Xbase++
LOCAL nSuccess
LOCAL oToken
LOCAL oHttp
LOCAL oResp
LOCAL oReply
LOCAL oFiles
LOCAL nFileStatus
LOCAL nBackupStatus
LOCAL oState
LOCAL cMailbox
LOCAL cBaseline
LOCAL nFullSync
LOCAL cCheckpoint
LOCAL oIds
LOCAL oBaseUrl
LOCAL oUrl
LOCAL cPageToken
LOCAL nMore
LOCAL oChangeTypes
LOCAL oRecord
LOCAL oEventPath
LOCAL h
LOCAL t
LOCAL j
LOCAL m
LOCAL oMessages
LOCAL oCachedMessage
LOCAL i
LOCAL cMessageId

nSuccess := 0

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

oToken := CreateObject("Chilkat.JsonObject")
nSuccess := oToken:LoadFile("gmail-token.json")
IF (nSuccess != 1)
    ? "Could not read gmail-token.json from the private working directory."
    oToken:destroy()
    RETURN
ENDIF

IF ((oToken:JsonTypeOf("access_token") != 1) .OR. (oToken:StringOfEquals("access_token", "", 1) == 1))
    ? "An OAuth access token is required."
    oToken:destroy()
    RETURN
ENDIF

oHttp := CreateObject("Chilkat.Http")
oHttp:RequireSslCertVerify := 1
oHttp:AuthToken := oToken:StringOf("access_token")
oResp := CreateObject("Chilkat.HttpResponse")
oReply := CreateObject("Chilkat.JsonObject")
oFiles := CreateObject("Chilkat.FileAccess")
//  Recover the previous complete file if a run stopped during replacement.
nFileStatus := oFiles:FileExists3("gmail-sync.json")
IF (nFileStatus < 0)
    ? "Could not inspect gmail-sync.json."
    oToken:destroy()
    oHttp:destroy()
    oResp:destroy()
    oReply:destroy()
    oFiles:destroy()
    RETURN
ENDIF

IF (nFileStatus == 0)
    nBackupStatus := oFiles:FileExists3("gmail-sync.json.previous")
    IF (nBackupStatus < 0)
        ? "Could not inspect the backup file."
        oToken:destroy()
        oHttp:destroy()
        oResp:destroy()
        oReply:destroy()
        oFiles:destroy()
        RETURN
    ENDIF

    IF (nBackupStatus == 1)
        nSuccess := oFiles:FileRename("gmail-sync.json.previous", "gmail-sync.json")
        IF (nSuccess != 1)
            ? "Could not restore the previous complete file."
            oToken:destroy()
            oHttp:destroy()
            oResp:destroy()
            oReply:destroy()
            oFiles:destroy()
            RETURN
        ENDIF

        nFileStatus := 1
    ENDIF

ENDIF

oState := CreateObject("Chilkat.JsonObject")
IF (nFileStatus == 1)
    nSuccess := oState:LoadFile("gmail-sync.json")
    IF (nSuccess != 1)
        ? "Could not read the existing synchronization state."
        oToken:destroy()
        oHttp:destroy()
        oResp:destroy()
        oReply:destroy()
        oFiles:destroy()
        oState:destroy()
        RETURN
    ENDIF

    IF ((oState:JsonTypeOf("historyId") != 1) .OR. (oState:JsonTypeOf("messages") != 3) .OR. (oState:JsonTypeOf("emailAddress") != 1))
        ? "The synchronization state is incomplete. Restore its previous complete copy."
        oToken:destroy()
        oHttp:destroy()
        oResp:destroy()
        oReply:destroy()
        oFiles:destroy()
        oState:destroy()
        RETURN
    ENDIF

ENDIF

nSuccess := oHttp:HttpNoBody("GET", "https://gmail.googleapis.com/gmail/v1/users/me/profile", oResp)
IF (oResp:StatusCode == 0)
    ? "Gmail did not return an HTTP response."
    oToken:destroy()
    oHttp:destroy()
    oResp:destroy()
    oReply:destroy()
    oFiles:destroy()
    oState:destroy()
    RETURN
ENDIF

IF ((nSuccess != 1) .OR. (oResp:StatusCode < 200) .OR. (oResp:StatusCode >= 300))
    ? "Gmail HTTP " + Str(oResp:StatusCode)
    nSuccess := oReply:Load(oResp:BodyStr)
    IF (nSuccess == 1)
        ? oReply:StringOf("error.message")
    ENDIF

    oToken:destroy()
    oHttp:destroy()
    oResp:destroy()
    oReply:destroy()
    oFiles:destroy()
    oState:destroy()
    RETURN
ENDIF

nSuccess := oReply:Load(oResp:BodyStr)
IF (nSuccess != 1)
    ? "Expected a Gmail JSON response."
    oToken:destroy()
    oHttp:destroy()
    oResp:destroy()
    oReply:destroy()
    oFiles:destroy()
    oState:destroy()
    RETURN
ENDIF

IF ((oReply:JsonTypeOf("emailAddress") != 1) .OR. (oReply:StringOfEquals("emailAddress", "", 1) == 1))
    ? "Expected emailAddress in the response."
    oToken:destroy()
    oHttp:destroy()
    oResp:destroy()
    oReply:destroy()
    oFiles:destroy()
    oState:destroy()
    RETURN
ENDIF

IF ((oReply:JsonTypeOf("historyId") != 1) .OR. (oReply:StringOfEquals("historyId", "", 1) == 1))
    ? "Expected historyId in the response."
    oToken:destroy()
    oHttp:destroy()
    oResp:destroy()
    oReply:destroy()
    oFiles:destroy()
    oState:destroy()
    RETURN
ENDIF

cMailbox := oReply:StringOf("emailAddress")
cBaseline := oReply:StringOf("historyId")
IF (nFileStatus == 1)
    IF (oState:StringOfEquals("emailAddress", cMailbox, 0) != 1)
        ? "Use a separate synchronization file for this mailbox."
        oToken:destroy()
        oHttp:destroy()
        oResp:destroy()
        oReply:destroy()
        oFiles:destroy()
        oState:destroy()
        RETURN
    ENDIF

ENDIF

nFullSync := nFileStatus == 0
cCheckpoint := cBaseline
oIds := CreateObject("Chilkat.StringArray")
oIds:Unique := 1
oBaseUrl := CreateObject("Chilkat.StringBuilder")
oUrl := CreateObject("Chilkat.StringBuilder")
cPageToken := ""
nMore := 1

IF (nFullSync != 1)
    oBaseUrl:SetString("https://gmail.googleapis.com/gmail/v1/users/me/history?maxResults=500&startHistoryId=")
    oBaseUrl:Append(oHttp:UrlEncode(oState:StringOf("historyId")))
    oChangeTypes := CreateObject("Chilkat.StringTable")
    nSuccess := oChangeTypes:Append("messagesAdded")
    IF (nSuccess != 1)
        ? oChangeTypes:LastErrorText
        oToken:destroy()
        oHttp:destroy()
        oResp:destroy()
        oReply:destroy()
        oFiles:destroy()
        oState:destroy()
        oIds:destroy()
        oBaseUrl:destroy()
        oUrl:destroy()
        oChangeTypes:destroy()
        RETURN
    ENDIF

    nSuccess := oChangeTypes:Append("messagesDeleted")
    IF (nSuccess != 1)
        ? oChangeTypes:LastErrorText
        oToken:destroy()
        oHttp:destroy()
        oResp:destroy()
        oReply:destroy()
        oFiles:destroy()
        oState:destroy()
        oIds:destroy()
        oBaseUrl:destroy()
        oUrl:destroy()
        oChangeTypes:destroy()
        RETURN
    ENDIF

    nSuccess := oChangeTypes:Append("labelsAdded")
    IF (nSuccess != 1)
        ? oChangeTypes:LastErrorText
        oToken:destroy()
        oHttp:destroy()
        oResp:destroy()
        oReply:destroy()
        oFiles:destroy()
        oState:destroy()
        oIds:destroy()
        oBaseUrl:destroy()
        oUrl:destroy()
        oChangeTypes:destroy()
        RETURN
    ENDIF

    nSuccess := oChangeTypes:Append("labelsRemoved")
    IF (nSuccess != 1)
        ? oChangeTypes:LastErrorText
        oToken:destroy()
        oHttp:destroy()
        oResp:destroy()
        oReply:destroy()
        oFiles:destroy()
        oState:destroy()
        oIds:destroy()
        oBaseUrl:destroy()
        oUrl:destroy()
        oChangeTypes:destroy()
        RETURN
    ENDIF

    oRecord := CreateObject("Chilkat.JsonObject")
    oEventPath := CreateObject("Chilkat.StringBuilder")
    DO WHILE (nMore == 1)
        oUrl:SetString(oBaseUrl:GetAsString())
        oUrl:Append("&pageToken=")
        oUrl:Append(oHttp:UrlEncode(cPageToken))
        nSuccess := oHttp:HttpNoBody("GET", oUrl:GetAsString(), oResp)
        IF (oResp:StatusCode == 404)
            ? "History checkpoint expired. Rebuilding the cache."
            nFullSync := 1
            nMore := 0
        ELSE
            IF (oResp:StatusCode == 0)
                ? "Gmail did not return an HTTP response."
                oToken:destroy()
                oHttp:destroy()
                oResp:destroy()
                oReply:destroy()
                oFiles:destroy()
                oState:destroy()
                oIds:destroy()
                oBaseUrl:destroy()
                oUrl:destroy()
                oChangeTypes:destroy()
                oRecord:destroy()
                oEventPath:destroy()
                RETURN
            ENDIF

            IF ((nSuccess != 1) .OR. (oResp:StatusCode < 200) .OR. (oResp:StatusCode >= 300))
                ? "Gmail HTTP " + Str(oResp:StatusCode)
                nSuccess := oReply:Load(oResp:BodyStr)
                IF (nSuccess == 1)
                    ? oReply:StringOf("error.message")
                ENDIF

                oToken:destroy()
                oHttp:destroy()
                oResp:destroy()
                oReply:destroy()
                oFiles:destroy()
                oState:destroy()
                oIds:destroy()
                oBaseUrl:destroy()
                oUrl:destroy()
                oChangeTypes:destroy()
                oRecord:destroy()
                oEventPath:destroy()
                RETURN
            ENDIF

            nSuccess := oReply:Load(oResp:BodyStr)
            IF (nSuccess != 1)
                ? "Expected a Gmail JSON response."
                oToken:destroy()
                oHttp:destroy()
                oResp:destroy()
                oReply:destroy()
                oFiles:destroy()
                oState:destroy()
                oIds:destroy()
                oBaseUrl:destroy()
                oUrl:destroy()
                oChangeTypes:destroy()
                oRecord:destroy()
                oEventPath:destroy()
                RETURN
            ENDIF

            h := 0
            DO WHILE (h < oReply:SizeOfArray("history"))
                oReply:I := h
                nSuccess := oReply:ObjectOf2("history[i]", oRecord)
                IF (nSuccess != 1)
                    ? oReply:LastErrorText
                    oToken:destroy()
                    oHttp:destroy()
                    oResp:destroy()
                    oReply:destroy()
                    oFiles:destroy()
                    oState:destroy()
                    oIds:destroy()
                    oBaseUrl:destroy()
                    oUrl:destroy()
                    oChangeTypes:destroy()
                    oRecord:destroy()
                    oEventPath:destroy()
                    RETURN
                ENDIF

                t := 0
                DO WHILE (t < oChangeTypes:Count)
                    j := 0
                    DO WHILE (j < oRecord:SizeOfArray(oChangeTypes:StringAt(t)))
                        oEventPath:SetString(oChangeTypes:StringAt(t))
                        oEventPath:Append("[")
                        oEventPath:AppendInt(j)
                        oEventPath:Append("].message.id")
                        nSuccess := oIds:Append(oRecord:StringOf(oEventPath:GetAsString()))
                        IF (nSuccess != 1)
                            ? oIds:LastErrorText
                            oToken:destroy()
                            oHttp:destroy()
                            oResp:destroy()
                            oReply:destroy()
                            oFiles:destroy()
                            oState:destroy()
                            oIds:destroy()
                            oBaseUrl:destroy()
                            oUrl:destroy()
                            oChangeTypes:destroy()
                            oRecord:destroy()
                            oEventPath:destroy()
                            RETURN
                        ENDIF

                        j := j + 1
                    ENDDO
                    t := t + 1
                ENDDO
                h := h + 1
            ENDDO
            cPageToken := ""
            IF (oReply:JsonTypeOf("nextPageToken") == 1)
                cPageToken := oReply:StringOf("nextPageToken")
            ENDIF

            nMore := cPageToken != ""
            IF (nMore != 1)
                IF ((oReply:JsonTypeOf("historyId") != 1) .OR. (oReply:StringOfEquals("historyId", "", 1) == 1))
                    ? "Expected historyId in the response."
                    oToken:destroy()
                    oHttp:destroy()
                    oResp:destroy()
                    oReply:destroy()
                    oFiles:destroy()
                    oState:destroy()
                    oIds:destroy()
                    oBaseUrl:destroy()
                    oUrl:destroy()
                    oChangeTypes:destroy()
                    oRecord:destroy()
                    oEventPath:destroy()
                    RETURN
                ENDIF

                cCheckpoint := oReply:StringOf("historyId")
            ENDIF

        ENDIF

    ENDDO
ENDIF

IF (nFullSync == 1)
    //  Rebuild in memory. Any failure leaves the committed file available for a retry.
    oIds:Clear()
    oState:Clear()
    nSuccess := oState:UpdateString("emailAddress", cMailbox)
    IF (nSuccess != 1)
        ? oState:LastErrorText
        oToken:destroy()
        oHttp:destroy()
        oResp:destroy()
        oReply:destroy()
        oFiles:destroy()
        oState:destroy()
        oIds:destroy()
        oBaseUrl:destroy()
        oUrl:destroy()
        oChangeTypes:destroy()
        oRecord:destroy()
        oEventPath:destroy()
        RETURN
    ENDIF

    nSuccess := oState:UpdateNewObject("messages")
    IF (nSuccess != 1)
        ? oState:LastErrorText
        oToken:destroy()
        oHttp:destroy()
        oResp:destroy()
        oReply:destroy()
        oFiles:destroy()
        oState:destroy()
        oIds:destroy()
        oBaseUrl:destroy()
        oUrl:destroy()
        oChangeTypes:destroy()
        oRecord:destroy()
        oEventPath:destroy()
        RETURN
    ENDIF

    cCheckpoint := cBaseline
    cPageToken := ""
    nMore := 1
    DO WHILE (nMore == 1)
        oUrl:SetString("https://gmail.googleapis.com/gmail/v1/users/me/messages?maxResults=500&includeSpamTrash=true&pageToken=")
        oUrl:Append(oHttp:UrlEncode(cPageToken))
        nSuccess := oHttp:HttpNoBody("GET", oUrl:GetAsString(), oResp)
        IF (oResp:StatusCode == 0)
            ? "Gmail did not return an HTTP response."
            oToken:destroy()
            oHttp:destroy()
            oResp:destroy()
            oReply:destroy()
            oFiles:destroy()
            oState:destroy()
            oIds:destroy()
            oBaseUrl:destroy()
            oUrl:destroy()
            oChangeTypes:destroy()
            oRecord:destroy()
            oEventPath:destroy()
            RETURN
        ENDIF

        IF ((nSuccess != 1) .OR. (oResp:StatusCode < 200) .OR. (oResp:StatusCode >= 300))
            ? "Gmail HTTP " + Str(oResp:StatusCode)
            nSuccess := oReply:Load(oResp:BodyStr)
            IF (nSuccess == 1)
                ? oReply:StringOf("error.message")
            ENDIF

            oToken:destroy()
            oHttp:destroy()
            oResp:destroy()
            oReply:destroy()
            oFiles:destroy()
            oState:destroy()
            oIds:destroy()
            oBaseUrl:destroy()
            oUrl:destroy()
            oChangeTypes:destroy()
            oRecord:destroy()
            oEventPath:destroy()
            RETURN
        ENDIF

        nSuccess := oReply:Load(oResp:BodyStr)
        IF (nSuccess != 1)
            ? "Expected a Gmail JSON response."
            oToken:destroy()
            oHttp:destroy()
            oResp:destroy()
            oReply:destroy()
            oFiles:destroy()
            oState:destroy()
            oIds:destroy()
            oBaseUrl:destroy()
            oUrl:destroy()
            oChangeTypes:destroy()
            oRecord:destroy()
            oEventPath:destroy()
            RETURN
        ENDIF

        m := 0
        DO WHILE (m < oReply:SizeOfArray("messages"))
            oReply:I := m
            nSuccess := oIds:Append(oReply:StringOf("messages[i].id"))
            IF (nSuccess != 1)
                ? oIds:LastErrorText
                oToken:destroy()
                oHttp:destroy()
                oResp:destroy()
                oReply:destroy()
                oFiles:destroy()
                oState:destroy()
                oIds:destroy()
                oBaseUrl:destroy()
                oUrl:destroy()
                oChangeTypes:destroy()
                oRecord:destroy()
                oEventPath:destroy()
                RETURN
            ENDIF

            m := m + 1
        ENDDO
        cPageToken := ""
        IF (oReply:JsonTypeOf("nextPageToken") == 1)
            cPageToken := oReply:StringOf("nextPageToken")
        ENDIF

        nMore := cPageToken != ""
    ENDDO
ENDIF

oMessages := CreateObject("Chilkat.JsonObject")
nSuccess := oState:ObjectOf2("messages", oMessages)
IF (nSuccess != 1)
    ? oState:LastErrorText
    oToken:destroy()
    oHttp:destroy()
    oResp:destroy()
    oReply:destroy()
    oFiles:destroy()
    oState:destroy()
    oIds:destroy()
    oBaseUrl:destroy()
    oUrl:destroy()
    oChangeTypes:destroy()
    oRecord:destroy()
    oEventPath:destroy()
    oMessages:destroy()
    RETURN
ENDIF

oCachedMessage := CreateObject("Chilkat.JsonObject")
i := 0
DO WHILE (i < oIds:Count)
    cMessageId := oIds:GetString(i)
    oUrl:SetString("https://gmail.googleapis.com/gmail/v1/users/me/messages/")
    oUrl:Append(oHttp:UrlEncode(cMessageId))
    oUrl:Append("?format=minimal&fields=id,threadId,labelIds")
    nSuccess := oHttp:HttpNoBody("GET", oUrl:GetAsString(), oResp)
    IF (oResp:StatusCode == 404)
        IF (oMessages:HasMember(cMessageId) == 1)
            nSuccess := oMessages:Delete(cMessageId)
            IF (nSuccess != 1)
                ? oMessages:LastErrorText
                oToken:destroy()
                oHttp:destroy()
                oResp:destroy()
                oReply:destroy()
                oFiles:destroy()
                oState:destroy()
                oIds:destroy()
                oBaseUrl:destroy()
                oUrl:destroy()
                oChangeTypes:destroy()
                oRecord:destroy()
                oEventPath:destroy()
                oMessages:destroy()
                oCachedMessage:destroy()
                RETURN
            ENDIF

        ENDIF

        ? "Removed from cache: " + cMessageId
    ELSE
        IF (oResp:StatusCode == 0)
            ? "Gmail did not return an HTTP response."
            oToken:destroy()
            oHttp:destroy()
            oResp:destroy()
            oReply:destroy()
            oFiles:destroy()
            oState:destroy()
            oIds:destroy()
            oBaseUrl:destroy()
            oUrl:destroy()
            oChangeTypes:destroy()
            oRecord:destroy()
            oEventPath:destroy()
            oMessages:destroy()
            oCachedMessage:destroy()
            RETURN
        ENDIF

        IF ((nSuccess != 1) .OR. (oResp:StatusCode < 200) .OR. (oResp:StatusCode >= 300))
            ? "Gmail HTTP " + Str(oResp:StatusCode)
            nSuccess := oReply:Load(oResp:BodyStr)
            IF (nSuccess == 1)
                ? oReply:StringOf("error.message")
            ENDIF

            oToken:destroy()
            oHttp:destroy()
            oResp:destroy()
            oReply:destroy()
            oFiles:destroy()
            oState:destroy()
            oIds:destroy()
            oBaseUrl:destroy()
            oUrl:destroy()
            oChangeTypes:destroy()
            oRecord:destroy()
            oEventPath:destroy()
            oMessages:destroy()
            oCachedMessage:destroy()
            RETURN
        ENDIF

        nSuccess := oReply:Load(oResp:BodyStr)
        IF (nSuccess != 1)
            ? "Expected a Gmail JSON response."
            oToken:destroy()
            oHttp:destroy()
            oResp:destroy()
            oReply:destroy()
            oFiles:destroy()
            oState:destroy()
            oIds:destroy()
            oBaseUrl:destroy()
            oUrl:destroy()
            oChangeTypes:destroy()
            oRecord:destroy()
            oEventPath:destroy()
            oMessages:destroy()
            oCachedMessage:destroy()
            RETURN
        ENDIF

        IF (oReply:StringOfEquals("id", cMessageId, 1) != 1)
            ? "Unexpected message ID in the response."
            oToken:destroy()
            oHttp:destroy()
            oResp:destroy()
            oReply:destroy()
            oFiles:destroy()
            oState:destroy()
            oIds:destroy()
            oBaseUrl:destroy()
            oUrl:destroy()
            oChangeTypes:destroy()
            oRecord:destroy()
            oEventPath:destroy()
            oMessages:destroy()
            oCachedMessage:destroy()
            RETURN
        ENDIF

        nSuccess := oMessages:UpdateNewObject(cMessageId)
        IF (nSuccess != 1)
            ? oMessages:LastErrorText
            oToken:destroy()
            oHttp:destroy()
            oResp:destroy()
            oReply:destroy()
            oFiles:destroy()
            oState:destroy()
            oIds:destroy()
            oBaseUrl:destroy()
            oUrl:destroy()
            oChangeTypes:destroy()
            oRecord:destroy()
            oEventPath:destroy()
            oMessages:destroy()
            oCachedMessage:destroy()
            RETURN
        ENDIF

        nSuccess := oMessages:ObjectOf2(cMessageId, oCachedMessage)
        IF (nSuccess != 1)
            ? oMessages:LastErrorText
            oToken:destroy()
            oHttp:destroy()
            oResp:destroy()
            oReply:destroy()
            oFiles:destroy()
            oState:destroy()
            oIds:destroy()
            oBaseUrl:destroy()
            oUrl:destroy()
            oChangeTypes:destroy()
            oRecord:destroy()
            oEventPath:destroy()
            oMessages:destroy()
            oCachedMessage:destroy()
            RETURN
        ENDIF

        nSuccess := oCachedMessage:Load(oReply:Emit())
        IF (nSuccess != 1)
            ? oCachedMessage:LastErrorText
            oToken:destroy()
            oHttp:destroy()
            oResp:destroy()
            oReply:destroy()
            oFiles:destroy()
            oState:destroy()
            oIds:destroy()
            oBaseUrl:destroy()
            oUrl:destroy()
            oChangeTypes:destroy()
            oRecord:destroy()
            oEventPath:destroy()
            oMessages:destroy()
            oCachedMessage:destroy()
            RETURN
        ENDIF

        ? "Cached message: " + cMessageId
    ENDIF

    i := i + 1
ENDDO
nSuccess := oState:UpdateString("historyId", cCheckpoint)
IF (nSuccess != 1)
    ? oState:LastErrorText
    oToken:destroy()
    oHttp:destroy()
    oResp:destroy()
    oReply:destroy()
    oFiles:destroy()
    oState:destroy()
    oIds:destroy()
    oBaseUrl:destroy()
    oUrl:destroy()
    oChangeTypes:destroy()
    oRecord:destroy()
    oEventPath:destroy()
    oMessages:destroy()
    oCachedMessage:destroy()
    RETURN
ENDIF

//  Prepare the complete replacement before moving the last committed file.
nSuccess := oState:WriteFile("gmail-sync.json.new")
IF (nSuccess != 1)
    ? "Could not write the replacement file."
    oToken:destroy()
    oHttp:destroy()
    oResp:destroy()
    oReply:destroy()
    oFiles:destroy()
    oState:destroy()
    oIds:destroy()
    oBaseUrl:destroy()
    oUrl:destroy()
    oChangeTypes:destroy()
    oRecord:destroy()
    oEventPath:destroy()
    oMessages:destroy()
    oCachedMessage:destroy()
    RETURN
ENDIF

IF (oFiles:FileExists("gmail-sync.json") == 1)
    IF (oFiles:FileExists("gmail-sync.json.previous") == 1)
        nSuccess := oFiles:FileDelete("gmail-sync.json.previous")
        IF (nSuccess != 1)
            ? "Could not rotate the previous backup."
            oToken:destroy()
            oHttp:destroy()
            oResp:destroy()
            oReply:destroy()
            oFiles:destroy()
            oState:destroy()
            oIds:destroy()
            oBaseUrl:destroy()
            oUrl:destroy()
            oChangeTypes:destroy()
            oRecord:destroy()
            oEventPath:destroy()
            oMessages:destroy()
            oCachedMessage:destroy()
            RETURN
        ENDIF

    ENDIF

    nSuccess := oFiles:FileRename("gmail-sync.json", "gmail-sync.json.previous")
    IF (nSuccess != 1)
        ? "Could not retain the previous complete file."
        oToken:destroy()
        oHttp:destroy()
        oResp:destroy()
        oReply:destroy()
        oFiles:destroy()
        oState:destroy()
        oIds:destroy()
        oBaseUrl:destroy()
        oUrl:destroy()
        oChangeTypes:destroy()
        oRecord:destroy()
        oEventPath:destroy()
        oMessages:destroy()
        oCachedMessage:destroy()
        RETURN
    ENDIF

ENDIF

nSuccess := oFiles:FileRename("gmail-sync.json.new", "gmail-sync.json")
IF (nSuccess != 1)
    ? "Could not commit the replacement. The previous complete file is retained."
    oToken:destroy()
    oHttp:destroy()
    oResp:destroy()
    oReply:destroy()
    oFiles:destroy()
    oState:destroy()
    oIds:destroy()
    oBaseUrl:destroy()
    oUrl:destroy()
    oChangeTypes:destroy()
    oRecord:destroy()
    oEventPath:destroy()
    oMessages:destroy()
    oCachedMessage:destroy()
    RETURN
ENDIF

? "Synchronization committed. Cached messages: " + Str(oMessages:Size)
? "Saved history ID: " + cCheckpoint

oToken:destroy()
oHttp:destroy()
oResp:destroy()
oReply:destroy()
oFiles:destroy()
oState:destroy()
oIds:destroy()
oBaseUrl:destroy()
oUrl:destroy()
oChangeTypes:destroy()
oRecord:destroy()
oEventPath:destroy()
oMessages:destroy()
oCachedMessage:destroy()