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

Unicode C
#include <C_CkJsonObjectW.h>
#include <C_CkAuthGoogleW.h>
#include <C_CkSocketW.h>
#include <C_CkImapW.h>
#include <C_CkMailboxesW.h>

void ChilkatSample(void)
    {
    BOOL success;
    const wchar_t *mailbox;
    HCkJsonObjectW key;
    HCkAuthGoogleW auth;
    HCkSocketW connection;
    HCkImapW imap;
    HCkMailboxesW folders;
    int i;

    success = FALSE;

    //  Assumes Chilkat is unlocked. See Global Unlock Sample.

    mailbox = L"user@example.com";
    key = CkJsonObjectW_Create();
    success = CkJsonObjectW_LoadFile(key,L"gmail-service-account.json");
    if (success != TRUE) {
        wprintf(L"Could not load the private service-account key.\n");
        CkJsonObjectW_Dispose(key);
        return;
    }

    if ((CkJsonObjectW_StringOfEquals(key,L"type",L"service_account",TRUE) != TRUE) || (CkJsonObjectW_JsonTypeOf(key,L"private_key") != 1)) {
        wprintf(L"Expected a Google service-account JSON key.\n");
        CkJsonObjectW_Dispose(key);
        return;
    }

    auth = CkAuthGoogleW_Create();
    CkAuthGoogleW_putJsonKey(auth,CkJsonObjectW_emit(key));
    CkAuthGoogleW_putSubEmailAddress(auth,mailbox);
    CkAuthGoogleW_putScope(auth,L"https://www.googleapis.com/auth/gmail.imap_admin");
    CkAuthGoogleW_putExpireNumSeconds(auth,3600);
    connection = CkSocketW_Create();
    CkSocketW_putRequireSslCertVerify(connection,TRUE);
    success = CkSocketW_Connect(connection,L"www.googleapis.com",443,TRUE,10000);
    if (success != TRUE) {
        wprintf(L"Could not establish the Google token connection.\n");
        CkJsonObjectW_Dispose(key);
        CkAuthGoogleW_Dispose(auth);
        CkSocketW_Dispose(connection);
        return;
    }

    success = CkAuthGoogleW_ObtainAccessToken(auth,connection);
    CkSocketW_Close(connection,1000);
    if (success != TRUE) {
        wprintf(L"Check the key, domain-wide delegation client ID/scope, user, and computer clock.\n");
        CkJsonObjectW_Dispose(key);
        CkAuthGoogleW_Dispose(auth);
        CkSocketW_Dispose(connection);
        return;
    }

    imap = CkImapW_Create();
    CkImapW_putSsl(imap,TRUE);
    CkImapW_putPort(imap,993);
    CkImapW_putRequireSslCertVerify(imap,TRUE);
    CkImapW_putAuthMethod(imap,L"XOAUTH2");
    success = CkImapW_Connect(imap,L"imap.gmail.com");
    if (success != TRUE) {
        wprintf(L"Could not establish the Gmail IMAP TLS connection.\n");
        CkJsonObjectW_Dispose(key);
        CkAuthGoogleW_Dispose(auth);
        CkSocketW_Dispose(connection);
        CkImapW_Dispose(imap);
        return;
    }

    success = CkImapW_Login(imap,mailbox,CkAuthGoogleW_accessToken(auth));
    if (success != TRUE) {
        CkImapW_Disconnect(imap);
        wprintf(L"IMAP authentication failed. Check the mailbox, scope, expiry, and account policy.\n");
        CkJsonObjectW_Dispose(key);
        CkAuthGoogleW_Dispose(auth);
        CkSocketW_Dispose(connection);
        CkImapW_Dispose(imap);
        return;
    }

    folders = CkMailboxesW_Create();
    success = CkImapW_MbxList(imap,FALSE,L"",L"*",folders);
    if (success != TRUE) {
        CkImapW_Logout(imap);
        CkImapW_Disconnect(imap);
        wprintf(L"Could not list Gmail folders.\n");
        CkJsonObjectW_Dispose(key);
        CkAuthGoogleW_Dispose(auth);
        CkSocketW_Dispose(connection);
        CkImapW_Dispose(imap);
        CkMailboxesW_Dispose(folders);
        return;
    }

    //  With gmail.imap_admin, labels hidden by the user's Show in IMAP setting are included.
    i = 0;
    while ((i < CkMailboxesW_getCount(folders))) {
        wprintf(L"%s\n",CkMailboxesW_getName(folders,i));
        i = i + 1;
    }

    success = CkImapW_ExamineMailbox(imap,L"INBOX");
    if (success != TRUE) {
        CkImapW_Logout(imap);
        CkImapW_Disconnect(imap);
        wprintf(L"Could not examine the impersonated user's INBOX.\n");
        CkJsonObjectW_Dispose(key);
        CkAuthGoogleW_Dispose(auth);
        CkSocketW_Dispose(connection);
        CkImapW_Dispose(imap);
        CkMailboxesW_Dispose(folders);
        return;
    }

    wprintf(L"INBOX messages: %d\n",CkImapW_getNumMessages(imap));
    CkImapW_Logout(imap);
    CkImapW_Disconnect(imap);


    CkJsonObjectW_Dispose(key);
    CkAuthGoogleW_Dispose(auth);
    CkSocketW_Dispose(connection);
    CkImapW_Dispose(imap);
    CkMailboxesW_Dispose(folders);

    }