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

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 mailbox = "user@example.com";
var key = new CkJsonObject();
success = key.LoadFile("gmail-service-account.json");
if (success !== true) {
    console.log("Could not load the private service-account key.");
    return;
}

if ((key.StringOfEquals("type","service_account",true) !== true) || (key.JsonTypeOf("private_key") !== 1)) {
    console.log("Expected a Google service-account JSON key.");
    return;
}

var auth = new CkAuthGoogle();
auth.JsonKey = key.Emit();
auth.SubEmailAddress = mailbox;
auth.Scope = "https://www.googleapis.com/auth/gmail.imap_admin";
auth.ExpireNumSeconds = 3600;
var connection = new CkSocket();
connection.RequireSslCertVerify = true;
success = connection.Connect("www.googleapis.com",443,true,10000);
if (success !== true) {
    console.log("Could not establish the Google token connection.");
    return;
}

success = auth.ObtainAccessToken(connection);
connection.Close(1000);
if (success !== true) {
    console.log("Check the key, domain-wide delegation client ID/scope, user, and computer clock.");
    return;
}

var imap = new CkImap();
imap.Ssl = true;
imap.Port = 993;
imap.RequireSslCertVerify = true;
imap.AuthMethod = "XOAUTH2";
success = imap.Connect("imap.gmail.com");
if (success !== true) {
    console.log("Could not establish the Gmail IMAP TLS connection.");
    return;
}

success = imap.Login(mailbox,auth.AccessToken);
if (success !== true) {
    imap.Disconnect();
    console.log("IMAP authentication failed. Check the mailbox, scope, expiry, and account policy.");
    return;
}

var folders = new CkMailboxes();
success = imap.MbxList(false,"","*",folders);
if (success !== true) {
    imap.Logout();
    imap.Disconnect();
    console.log("Could not list Gmail folders.");
    return;
}

//  With gmail.imap_admin, labels hidden by the user's Show in IMAP setting are included.
var i = 0;
while ((i < folders.Count)) {
    console.log(folders.GetName(i));
    i = i+1;
}

success = imap.ExamineMailbox("INBOX");
if (success !== true) {
    imap.Logout();
    imap.Disconnect();
    console.log("Could not examine the impersonated user's INBOX.");
    return;
}

console.log("INBOX messages: " + imap.NumMessages);
imap.Logout();
imap.Disconnect();