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

Note
This example is intended for running within a Chilkat.Js embedded JavaScript engine. All Chilkat JavaScript examples require Chilkat v11.4.0 or greater.
JavaScript
var success = false;

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

var token = new CkJsonObject();
success = token.LoadFile("gmail-token.json");
if (success !== true) {
    console.log("Could not read gmail-token.json from the private working directory.");
    return;
}

if ((token.JsonTypeOf("access_token") !== 1) || (token.StringOfEquals("access_token","",true) == true)) {
    console.log("An OAuth access token is required.");
    return;
}

var http = new CkHttp();
http.RequireSslCertVerify = true;
http.AuthToken = token.StringOf("access_token");
var resp = new CkHttpResponse();
var reply = new CkJsonObject();
var searchQuery = "from:sender@example.com has:attachment filename:pdf";
var baseUrl = new CkStringBuilder();
baseUrl.Append("https://gmail.googleapis.com/gmail/v1/users/me/messages?maxResults=100&q=");
baseUrl.Append(http.UrlEncode(searchQuery));
var url = new CkStringBuilder();
var pageToken = "";
var page = new CkJsonObject();
var total = 0;
var more = true;
while ((more == true)) {
    url.SetString(baseUrl.GetAsString());
    url.Append("&pageToken=");
    url.Append(http.UrlEncode(pageToken));
    success = http.HttpNoBody("GET",url.GetAsString(),resp);
    if (resp.StatusCode == 0) {
        console.log("Gmail did not return an HTTP response.");
        return;
    }

    if ((success !== true) || (resp.StatusCode < 200) || (resp.StatusCode >= 300)) {
        console.log("Gmail HTTP " + resp.StatusCode);
        success = reply.Load(resp.BodyStr);
        if (success == true) {
            console.log(reply.StringOf("error.message"));
        }

        return;
    }

    success = reply.Load(resp.BodyStr);
    if (success !== true) {
        console.log("Expected a Gmail JSON response.");
        return;
    }

    //  Keep this page while individual message requests reuse reply.
    success = reply.MakeCopy(page);
    if (success !== true) {
        console.log(reply.LastErrorText);
        return;
    }

    var i = 0;
    while ((i < page.SizeOfArray("messages"))) {
        page.I = i;
        var 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.GetAsString(),resp);
        //  A message can disappear between the search and the metadata request.
        if (resp.StatusCode !== 404) {
            if (resp.StatusCode == 0) {
                console.log("Gmail did not return an HTTP response.");
                return;
            }

            if ((success !== true) || (resp.StatusCode < 200) || (resp.StatusCode >= 300)) {
                console.log("Gmail HTTP " + resp.StatusCode);
                success = reply.Load(resp.BodyStr);
                if (success == true) {
                    console.log(reply.StringOf("error.message"));
                }

                return;
            }

            success = reply.Load(resp.BodyStr);
            if (success !== true) {
                console.log("Expected a Gmail JSON response.");
                return;
            }

            console.log("Message: " + messageId);
            var h = 0;
            while ((h < reply.SizeOfArray("payload.headers"))) {
                reply.I = h;
                console.log(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") == 1) {
        pageToken = page.StringOf("nextPageToken");
    }

    more = pageToken !== "";
}

console.log("Matching messages read: " + total);