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 CkPython Downloads
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))