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.
Chilkat CkPerl Downloads
use chilkat();
$success = 0;
# Assumes Chilkat is unlocked. See Global Unlock Sample.
$mailbox = 'user@example.com';
$key = chilkat::CkJsonObject->new();
$success = $key->LoadFile("gmail-service-account.json");
if ($success != 1) {
print "Could not load the private service-account key." . "\r\n";
exit;
}
if (($key->StringOfEquals("type","service_account",1) != 1) or ($key->JsonTypeOf("private_key") != 1)) {
print "Expected a Google service-account JSON key." . "\r\n";
exit;
}
$auth = chilkat::CkAuthGoogle->new();
$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->new();
$connection->put_RequireSslCertVerify(1);
$success = $connection->Connect("www.googleapis.com",443,1,10000);
if ($success != 1) {
print "Could not establish the Google token connection." . "\r\n";
exit;
}
$success = $auth->ObtainAccessToken($connection);
$connection->Close(1000);
if ($success != 1) {
print "Check the key, domain-wide delegation client ID/scope, user, and computer clock." . "\r\n";
exit;
}
$imap = chilkat::CkImap->new();
$imap->put_Ssl(1);
$imap->put_Port(993);
$imap->put_RequireSslCertVerify(1);
$imap->put_AuthMethod("XOAUTH2");
$success = $imap->Connect("imap.gmail.com");
if ($success != 1) {
print "Could not establish the Gmail IMAP TLS connection." . "\r\n";
exit;
}
$success = $imap->Login($mailbox,$auth->accessToken());
if ($success != 1) {
$imap->Disconnect();
print "IMAP authentication failed. Check the mailbox, scope, expiry, and account policy." . "\r\n";
exit;
}
$folders = chilkat::CkMailboxes->new();
$success = $imap->MbxList(0,"","*",$folders);
if ($success != 1) {
$imap->Logout();
$imap->Disconnect();
print "Could not list Gmail folders." . "\r\n";
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) . "\r\n";
$i = $i + 1;
}
$success = $imap->ExamineMailbox("INBOX");
if ($success != 1) {
$imap->Logout();
$imap->Disconnect();
print "Could not examine the impersonated user's INBOX." . "\r\n";
exit;
}
print "INBOX messages: " . $imap->get_NumMessages() . "\r\n";
$imap->Logout();
$imap->Disconnect();