Sample code for 30+ languages & platforms
Objective-C Requires Chilkat v11.0.0+

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.

Google documentation

Chilkat Objective-C Downloads

Objective-C
#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);