Gmail IMAP: Workspace Service Account with a JSON Key
Use a service-account JSON key with Google Workspace domain-wide delegation. A Workspace administrator must authorize the service account's numeric OAuth client ID for https://mail.google.com/. Set SubEmailAddress to the Workspace user whose active Gmail mailbox is being accessed, and use that same address for IMAP login.
A service account has no Gmail mailbox of its own; leaving the impersonated user empty does not grant access to a personal Gmail account. The signed JWT exchange yields a short-lived token without a refresh token. Obtain another when needed, protect the private key, and keep the computer clock accurate.
This example lists visible folders and examines INBOX read-only. For the different visibility rules of the IMAP-only administrative scope, see gmail.imap_admin delegation.
See the Gmail SMTP, IMAP, and POP3 guide for current authentication choices and Gmail-specific examples.
v11.4.0 or greater.
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://mail.google.com/";
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;
}
// List the labels visible through ordinary full-mail IMAP access.
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();