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 Objective-C Downloads
#import <CkoJsonObject.h>
#import <CkoHttp.h>
#import <CkoHttpResponse.h>
#import <CkoFileAccess.h>
#import <NSString.h>
#import <CkoStringArray.h>
#import <CkoStringBuilder.h>
#import <CkoStringTable.h>
BOOL success = NO;
// Assumes Chilkat is unlocked. See Global Unlock Sample.
CkoJsonObject *token = [[CkoJsonObject alloc] init];
success = [token LoadFile: @"gmail-token.json"];
if (success != YES) {
NSLog(@"%@",@"Could not read gmail-token.json from the private working directory.");
return;
}
if (([[token JsonTypeOf: @"access_token"] intValue] != 1) || ([token StringOfEquals: @"access_token" value: @"" caseSensitive: YES] == YES)) {
NSLog(@"%@",@"An OAuth access token is required.");
return;
}
CkoHttp *http = [[CkoHttp alloc] init];
http.RequireSslCertVerify = YES;
http.AuthToken = [token StringOf: @"access_token"];
CkoHttpResponse *resp = [[CkoHttpResponse alloc] init];
CkoJsonObject *reply = [[CkoJsonObject alloc] init];
CkoFileAccess *files = [[CkoFileAccess alloc] init];
// Recover the previous complete file if a run stopped during replacement.
int fileStatus = [[files FileExists3: @"gmail-sync.json"] intValue];
if (fileStatus < 0) {
NSLog(@"%@",@"Could not inspect gmail-sync.json.");
return;
}
if (fileStatus == 0) {
int backupStatus = [[files FileExists3: @"gmail-sync.json.previous"] intValue];
if (backupStatus < 0) {
NSLog(@"%@",@"Could not inspect the backup file.");
return;
}
if (backupStatus == 1) {
success = [files FileRename: @"gmail-sync.json.previous" newPath: @"gmail-sync.json"];
if (success != YES) {
NSLog(@"%@",@"Could not restore the previous complete file.");
return;
}
fileStatus = 1;
}
}
CkoJsonObject *state = [[CkoJsonObject alloc] init];
if (fileStatus == 1) {
success = [state LoadFile: @"gmail-sync.json"];
if (success != YES) {
NSLog(@"%@",@"Could not read the existing synchronization state.");
return;
}
if (([[state JsonTypeOf: @"historyId"] intValue] != 1) || ([[state JsonTypeOf: @"messages"] intValue] != 3) || ([[state JsonTypeOf: @"emailAddress"] intValue] != 1)) {
NSLog(@"%@",@"The synchronization state is incomplete. Restore its previous complete copy.");
return;
}
}
success = [http HttpNoBody: @"GET" url: @"https://gmail.googleapis.com/gmail/v1/users/me/profile" response: resp];
if ([resp.StatusCode intValue] == 0) {
NSLog(@"%@",@"Gmail did not return an HTTP response.");
return;
}
if ((success != YES) || ([resp.StatusCode intValue] < 200) || ([resp.StatusCode intValue] >= 300)) {
NSLog(@"%@%d",@"Gmail HTTP ",[resp.StatusCode intValue]);
success = [reply Load: resp.BodyStr];
if (success == YES) {
NSLog(@"%@",[reply StringOf: @"error.message"]);
}
return;
}
success = [reply Load: resp.BodyStr];
if (success != YES) {
NSLog(@"%@",@"Expected a Gmail JSON response.");
return;
}
if (([[reply JsonTypeOf: @"emailAddress"] intValue] != 1) || ([reply StringOfEquals: @"emailAddress" value: @"" caseSensitive: YES] == YES)) {
NSLog(@"%@",@"Expected emailAddress in the response.");
return;
}
if (([[reply JsonTypeOf: @"historyId"] intValue] != 1) || ([reply StringOfEquals: @"historyId" value: @"" caseSensitive: YES] == YES)) {
NSLog(@"%@",@"Expected historyId in the response.");
return;
}
NSString *mailbox = [reply StringOf: @"emailAddress"];
NSString *baseline = [reply StringOf: @"historyId"];
if (fileStatus == 1) {
if ([state StringOfEquals: @"emailAddress" value: mailbox caseSensitive: NO] != YES) {
NSLog(@"%@",@"Use a separate synchronization file for this mailbox.");
return;
}
}
BOOL fullSync = fileStatus == 0;
NSString *checkpoint = baseline;
CkoStringArray *ids = [[CkoStringArray alloc] init];
ids.Unique = YES;
CkoStringBuilder *baseUrl = [[CkoStringBuilder alloc] init];
CkoStringBuilder *url = [[CkoStringBuilder alloc] init];
NSString *pageToken = @"";
BOOL more = YES;
if (fullSync != YES) {
[baseUrl SetString: @"https://gmail.googleapis.com/gmail/v1/users/me/history?maxResults=500&startHistoryId="];
[baseUrl Append: [http UrlEncode: [state StringOf: @"historyId"]]];
CkoStringTable *changeTypes = [[CkoStringTable alloc] init];
success = [changeTypes Append: @"messagesAdded"];
if (success != YES) {
NSLog(@"%@",changeTypes.LastErrorText);
return;
}
success = [changeTypes Append: @"messagesDeleted"];
if (success != YES) {
NSLog(@"%@",changeTypes.LastErrorText);
return;
}
success = [changeTypes Append: @"labelsAdded"];
if (success != YES) {
NSLog(@"%@",changeTypes.LastErrorText);
return;
}
success = [changeTypes Append: @"labelsRemoved"];
if (success != YES) {
NSLog(@"%@",changeTypes.LastErrorText);
return;
}
CkoJsonObject *record = [[CkoJsonObject alloc] init];
CkoStringBuilder *eventPath = [[CkoStringBuilder alloc] init];
while ((more == YES)) {
[url SetString: [baseUrl GetAsString]];
[url Append: @"&pageToken="];
[url Append: [http UrlEncode: pageToken]];
success = [http HttpNoBody: @"GET" url: [url GetAsString] response: resp];
if ([resp.StatusCode intValue] == 404) {
NSLog(@"%@",@"History checkpoint expired. Rebuilding the cache.");
fullSync = YES;
more = NO;
}
else {
if ([resp.StatusCode intValue] == 0) {
NSLog(@"%@",@"Gmail did not return an HTTP response.");
return;
}
if ((success != YES) || ([resp.StatusCode intValue] < 200) || ([resp.StatusCode intValue] >= 300)) {
NSLog(@"%@%d",@"Gmail HTTP ",[resp.StatusCode intValue]);
success = [reply Load: resp.BodyStr];
if (success == YES) {
NSLog(@"%@",[reply StringOf: @"error.message"]);
}
return;
}
success = [reply Load: resp.BodyStr];
if (success != YES) {
NSLog(@"%@",@"Expected a Gmail JSON response.");
return;
}
int h = 0;
while ((h < [[reply SizeOfArray: @"history"] intValue])) {
reply.I = [NSNumber numberWithInt: h];
success = [reply ObjectOf2: @"history[i]" jsonObj: record];
if (success != YES) {
NSLog(@"%@",reply.LastErrorText);
return;
}
int t = 0;
while ((t < [changeTypes.Count intValue])) {
int j = 0;
while ((j < [[record SizeOfArray: [changeTypes StringAt: [NSNumber numberWithInt: t]]] intValue])) {
[eventPath SetString: [changeTypes StringAt: [NSNumber numberWithInt: t]]];
[eventPath Append: @"["];
[eventPath AppendInt: [NSNumber numberWithInt: j]];
[eventPath Append: @"].message.id"];
success = [ids Append: [record StringOf: [eventPath GetAsString]]];
if (success != YES) {
NSLog(@"%@",ids.LastErrorText);
return;
}
j = j + 1;
}
t = t + 1;
}
h = h + 1;
}
pageToken = @"";
if ([[reply JsonTypeOf: @"nextPageToken"] intValue] == 1) {
pageToken = [reply StringOf: @"nextPageToken"];
}
more = pageToken != @"";
if (more != YES) {
if (([[reply JsonTypeOf: @"historyId"] intValue] != 1) || ([reply StringOfEquals: @"historyId" value: @"" caseSensitive: YES] == YES)) {
NSLog(@"%@",@"Expected historyId in the response.");
return;
}
checkpoint = [reply StringOf: @"historyId"];
}
}
}
}
if (fullSync == YES) {
// Rebuild in memory. Any failure leaves the committed file available for a retry.
[ids Clear];
[state Clear];
success = [state UpdateString: @"emailAddress" value: mailbox];
if (success != YES) {
NSLog(@"%@",state.LastErrorText);
return;
}
success = [state UpdateNewObject: @"messages"];
if (success != YES) {
NSLog(@"%@",state.LastErrorText);
return;
}
checkpoint = baseline;
pageToken = @"";
more = YES;
while ((more == YES)) {
[url SetString: @"https://gmail.googleapis.com/gmail/v1/users/me/messages?maxResults=500&includeSpamTrash=true&pageToken="];
[url Append: [http UrlEncode: pageToken]];
success = [http HttpNoBody: @"GET" url: [url GetAsString] response: resp];
if ([resp.StatusCode intValue] == 0) {
NSLog(@"%@",@"Gmail did not return an HTTP response.");
return;
}
if ((success != YES) || ([resp.StatusCode intValue] < 200) || ([resp.StatusCode intValue] >= 300)) {
NSLog(@"%@%d",@"Gmail HTTP ",[resp.StatusCode intValue]);
success = [reply Load: resp.BodyStr];
if (success == YES) {
NSLog(@"%@",[reply StringOf: @"error.message"]);
}
return;
}
success = [reply Load: resp.BodyStr];
if (success != YES) {
NSLog(@"%@",@"Expected a Gmail JSON response.");
return;
}
int m = 0;
while ((m < [[reply SizeOfArray: @"messages"] intValue])) {
reply.I = [NSNumber numberWithInt: m];
success = [ids Append: [reply StringOf: @"messages[i].id"]];
if (success != YES) {
NSLog(@"%@",ids.LastErrorText);
return;
}
m = m + 1;
}
pageToken = @"";
if ([[reply JsonTypeOf: @"nextPageToken"] intValue] == 1) {
pageToken = [reply StringOf: @"nextPageToken"];
}
more = pageToken != @"";
}
}
CkoJsonObject *messages = [[CkoJsonObject alloc] init];
success = [state ObjectOf2: @"messages" jsonObj: messages];
if (success != YES) {
NSLog(@"%@",state.LastErrorText);
return;
}
CkoJsonObject *cachedMessage = [[CkoJsonObject alloc] init];
int i = 0;
while ((i < [ids.Count intValue])) {
NSString *messageId = [ids GetString: [NSNumber numberWithInt: i]];
[url SetString: @"https://gmail.googleapis.com/gmail/v1/users/me/messages/"];
[url Append: [http UrlEncode: messageId]];
[url Append: @"?format=minimal&fields=id,threadId,labelIds"];
success = [http HttpNoBody: @"GET" url: [url GetAsString] response: resp];
if ([resp.StatusCode intValue] == 404) {
if ([messages HasMember: messageId] == YES) {
success = [messages Delete: messageId];
if (success != YES) {
NSLog(@"%@",messages.LastErrorText);
return;
}
}
NSLog(@"%@%@",@"Removed from cache: ",messageId);
}
else {
if ([resp.StatusCode intValue] == 0) {
NSLog(@"%@",@"Gmail did not return an HTTP response.");
return;
}
if ((success != YES) || ([resp.StatusCode intValue] < 200) || ([resp.StatusCode intValue] >= 300)) {
NSLog(@"%@%d",@"Gmail HTTP ",[resp.StatusCode intValue]);
success = [reply Load: resp.BodyStr];
if (success == YES) {
NSLog(@"%@",[reply StringOf: @"error.message"]);
}
return;
}
success = [reply Load: resp.BodyStr];
if (success != YES) {
NSLog(@"%@",@"Expected a Gmail JSON response.");
return;
}
if ([reply StringOfEquals: @"id" value: messageId caseSensitive: YES] != YES) {
NSLog(@"%@",@"Unexpected message ID in the response.");
return;
}
success = [messages UpdateNewObject: messageId];
if (success != YES) {
NSLog(@"%@",messages.LastErrorText);
return;
}
success = [messages ObjectOf2: messageId jsonObj: cachedMessage];
if (success != YES) {
NSLog(@"%@",messages.LastErrorText);
return;
}
success = [cachedMessage Load: [reply Emit]];
if (success != YES) {
NSLog(@"%@",cachedMessage.LastErrorText);
return;
}
NSLog(@"%@%@",@"Cached message: ",messageId);
}
i = i + 1;
}
success = [state UpdateString: @"historyId" value: checkpoint];
if (success != YES) {
NSLog(@"%@",state.LastErrorText);
return;
}
// Prepare the complete replacement before moving the last committed file.
success = [state WriteFile: @"gmail-sync.json.new"];
if (success != YES) {
NSLog(@"%@",@"Could not write the replacement file.");
return;
}
if ([files FileExists: @"gmail-sync.json"] == YES) {
if ([files FileExists: @"gmail-sync.json.previous"] == YES) {
success = [files FileDelete: @"gmail-sync.json.previous"];
if (success != YES) {
NSLog(@"%@",@"Could not rotate the previous backup.");
return;
}
}
success = [files FileRename: @"gmail-sync.json" newPath: @"gmail-sync.json.previous"];
if (success != YES) {
NSLog(@"%@",@"Could not retain the previous complete file.");
return;
}
}
success = [files FileRename: @"gmail-sync.json.new" newPath: @"gmail-sync.json"];
if (success != YES) {
NSLog(@"%@",@"Could not commit the replacement. The previous complete file is retained.");
return;
}
NSLog(@"%@%d",@"Synchronization committed. Cached messages: ",[messages.Size intValue]);
NSLog(@"%@%@",@"Saved history ID: ",checkpoint);