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

CkPython
import sys
import chilkat

success = False

#  Assumes Chilkat is unlocked. See Global Unlock Sample.

token = chilkat.CkJsonObject()
success = token.LoadFile("gmail-token.json")
if (success != True):
    print("Could not read gmail-token.json from the private working directory.")
    sys.exit()

if ((token.JsonTypeOf("access_token") != 1) or (token.StringOfEquals("access_token","",True) == True)):
    print("An OAuth access token is required.")
    sys.exit()

http = chilkat.CkHttp()
http.put_RequireSslCertVerify(True)
http.put_AuthToken(token.stringOf("access_token"))
resp = chilkat.CkHttpResponse()
reply = chilkat.CkJsonObject()
searchQuery = "from:sender@example.com has:attachment filename:pdf"
baseUrl = chilkat.CkStringBuilder()
baseUrl.Append("https://gmail.googleapis.com/gmail/v1/users/me/messages?maxResults=100&q=")
baseUrl.Append(http.urlEncode(searchQuery))
url = chilkat.CkStringBuilder()
pageToken = ""
page = chilkat.CkJsonObject()
total = 0
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.get_StatusCode() == 0):
        print("Gmail did not return an HTTP response.")
        sys.exit()

    if ((success != True) or (resp.get_StatusCode() < 200) or (resp.get_StatusCode() >= 300)):
        print("Gmail HTTP " + str(resp.get_StatusCode()))
        success = reply.Load(resp.bodyStr())
        if (success == True):
            print(reply.stringOf("error.message"))

        sys.exit()

    success = reply.Load(resp.bodyStr())
    if (success != True):
        print("Expected a Gmail JSON response.")
        sys.exit()

    #  Keep this page while individual message requests reuse reply.
    success = reply.MakeCopy(page)
    if (success != True):
        print(reply.lastErrorText())
        sys.exit()

    i = 0
    while (i < page.SizeOfArray("messages")) :
        page.put_I(i)
        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.get_StatusCode() != 404):
            if (resp.get_StatusCode() == 0):
                print("Gmail did not return an HTTP response.")
                sys.exit()

            if ((success != True) or (resp.get_StatusCode() < 200) or (resp.get_StatusCode() >= 300)):
                print("Gmail HTTP " + str(resp.get_StatusCode()))
                success = reply.Load(resp.bodyStr())
                if (success == True):
                    print(reply.stringOf("error.message"))

                sys.exit()

            success = reply.Load(resp.bodyStr())
            if (success != True):
                print("Expected a Gmail JSON response.")
                sys.exit()

            print("Message: " + messageId)
            h = 0
            while (h < reply.SizeOfArray("payload.headers")) :
                reply.put_I(h)
                print(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 != ""

print("Matching messages read: " + str(total))