Search Gmail by sender, subject, date, or attachment
See more GMail REST API Examples
Choose a Gmail search query, follow every result page, and fetch From and Subject headers for each match. Edit the query to use operators such as from:, subject:, after:, before:, has:attachment, and filename:. Quoted phrases and special characters are URL-encoded once.
Gmail search dates use midnight Pacific Standard Time. Use Unix timestamps in seconds for exact date boundaries in another timezone. Spam and Trash are excluded unless includeSpamTrash=true is added. Search requires gmail.readonly or a broader mail scope. Query searches are unavailable with gmail.metadata.
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 <NSString.h>
#import <CkoStringBuilder.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];
NSString *searchQuery = @"from:sender@example.com has:attachment filename:pdf";
CkoStringBuilder *baseUrl = [[CkoStringBuilder alloc] init];
[baseUrl Append: @"https://gmail.googleapis.com/gmail/v1/users/me/messages?maxResults=100&q="];
[baseUrl Append: [http UrlEncode: searchQuery]];
CkoStringBuilder *url = [[CkoStringBuilder alloc] init];
NSString *pageToken = @"";
CkoJsonObject *page = [[CkoJsonObject alloc] init];
int total = 0;
BOOL more = YES;
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] == 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;
}
// Keep this page while individual message requests reuse reply.
success = [reply MakeCopy: page];
if (success != YES) {
NSLog(@"%@",reply.LastErrorText);
return;
}
int i = 0;
while ((i < [[page SizeOfArray: @"messages"] intValue])) {
page.I = [NSNumber numberWithInt: i];
NSString *messageId = [page StringOf: @"messages[i].id"];
[url SetString: @"https://gmail.googleapis.com/gmail/v1/users/me/messages/"];
[url Append: [http UrlEncode: messageId]];
[url Append: @"?format=metadata&metadataHeaders=From&metadataHeaders=Subject"];
success = [http HttpNoBody: @"GET" url: [url GetAsString] response: resp];
// A message can disappear between the search and the metadata request.
if ([resp.StatusCode intValue] != 404) {
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;
}
NSLog(@"%@%@",@"Message: ",messageId);
int h = 0;
while ((h < [[reply SizeOfArray: @"payload.headers"] intValue])) {
reply.I = [NSNumber numberWithInt: h];
NSLog(@"%@%@%@",[reply StringOf: @"payload.headers[i].name"],@": ",[reply StringOf: @"payload.headers[i].value"]);
h = h + 1;
}
total = total + 1;
}
i = i + 1;
}
pageToken = @"";
if ([[page JsonTypeOf: @"nextPageToken"] intValue] == 1) {
pageToken = [page StringOf: @"nextPageToken"];
}
more = pageToken != @"";
}
NSLog(@"%@%d",@"Matching messages read: ",total);