Sample code for 30+ languages & platforms
CkPython Requires Chilkat v11.1.0+

Gmail IMAP: Workspace Domain-Wide Delegation

See more GMail SMTP/IMAP/POP Examples

Use a JSON service-account key to impersonate a Workspace user for IMAP with https://www.googleapis.com/auth/gmail.imap_admin. A Workspace administrator must authorize the service account's numeric OAuth client ID for this exact scope in domain-wide delegation. The impersonated user must have an active Gmail mailbox.

This IMAP-only scope reveals labels hidden by Show in IMAP and messages excluded by the user's folder-size limit. It does not authorize SMTP or POP and is not available for personal Gmail accounts or ordinary user-consent flows. Workspace administrative access policies still apply.

Protect the private key and limit who can execute the delegated application. The signed JWT exchange produces a short-lived token without a refresh token; obtain another when necessary and reconnect. Keep the computer clock accurate. This example lists folders and examines INBOX read-only without printing credentials.

Google documentation

Chilkat CkPython Downloads

CkPython
import sys
import chilkat

success = False

#  Assumes Chilkat is unlocked. See Global Unlock Sample.

mailbox = "user@example.com"
key = chilkat.CkJsonObject()
success = key.LoadFile("gmail-service-account.json")
if (success != True):
    print("Could not load the private service-account key.")
    sys.exit()

if ((key.StringOfEquals("type","service_account",True) != True) or (key.JsonTypeOf("private_key") != 1)):
    print("Expected a Google service-account JSON key.")
    sys.exit()

auth = chilkat.CkAuthGoogle()
auth.put_JsonKey(key.emit())
auth.put_SubEmailAddress(mailbox)
auth.put_Scope("https://www.googleapis.com/auth/gmail.imap_admin")
auth.put_ExpireNumSeconds(3600)
connection = chilkat.CkSocket()
connection.put_RequireSslCertVerify(True)
success = connection.Connect("www.googleapis.com",443,True,10000)
if (success != True):
    print("Could not establish the Google token connection.")
    sys.exit()

success = auth.ObtainAccessToken(connection)
connection.Close(1000)
if (success != True):
    print("Check the key, domain-wide delegation client ID/scope, user, and computer clock.")
    sys.exit()

imap = chilkat.CkImap()
imap.put_Ssl(True)
imap.put_Port(993)
imap.put_RequireSslCertVerify(True)
imap.put_AuthMethod("XOAUTH2")
success = imap.Connect("imap.gmail.com")
if (success != True):
    print("Could not establish the Gmail IMAP TLS connection.")
    sys.exit()

success = imap.Login(mailbox,auth.accessToken())
if (success != True):
    imap.Disconnect()
    print("IMAP authentication failed. Check the mailbox, scope, expiry, and account policy.")
    sys.exit()

folders = chilkat.CkMailboxes()
success = imap.MbxList(False,"","*",folders)
if (success != True):
    imap.Logout()
    imap.Disconnect()
    print("Could not list Gmail folders.")
    sys.exit()

#  With gmail.imap_admin, labels hidden by the user's Show in IMAP setting are included.
i = 0
while (i < folders.get_Count()) :
    print(folders.getName(i))
    i = i + 1

success = imap.ExamineMailbox("INBOX")
if (success != True):
    imap.Logout()
    imap.Disconnect()
    print("Could not examine the impersonated user's INBOX.")
    sys.exit()

print("INBOX messages: " + str(imap.get_NumMessages()))
imap.Logout()
imap.Disconnect()