Gmail IMAP: Authenticate and Open the Inbox Read-Only
See more GMail SMTP/IMAP/POP Examples
Connect to imap.gmail.com:993 over implicit TLS, authenticate with XOAUTH2, and examine INBOX without changing messages. ExamineMailbox opens the mailbox read-only; the count is for the selected mailbox, not the entire Gmail account. Logout and disconnect explicitly when finished.
For personal Gmail accounts, IMAP has been always enabled since January 2025; the old Enable IMAP switch is no longer needed. Workspace administrators can restrict IMAP access and allowed OAuth clients. Use the mailbox that authorized the token, not the application's client ID.
Gmail exposes labels as IMAP folders. One message can appear under several labels, so summing folder counts can double-count it. Gmail special-folder names can be localized; INBOX is the protocol-defined exception. Discover other folders through LIST special-use attributes instead of assuming English names. Long-lived connections may be closed when the access token expires; refresh and reconnect.
This example reads gmail-mail-token.json from a private working directory. Authorize the account first, then refresh the access token before it expires. The separate filename avoids confusing this full-mail grant with a narrower Gmail REST token. Store credentials in protected application storage; never distribute a user's token file with an application.
Gmail SMTP, IMAP, and POP3 use the https://mail.google.com/ OAuth scope. Narrower Gmail REST scopes such as gmail.send or gmail.readonly do not authorize these protocols. Public applications using this restricted scope must meet Google's verification requirements. See Gmail OAuth scopes and XOAUTH2.
Chilkat Unicode C++ Downloads
#include <CkJsonObjectW.h>
#include <CkImapW.h>
void ChilkatSample(void)
{
bool success = false;
// Assumes Chilkat is unlocked. See Global Unlock Sample.
CkJsonObjectW token;
success = token.LoadFile(L"gmail-mail-token.json");
if (success != true) {
wprintf(L"Could not read gmail-mail-token.json from the private working directory.\n");
return;
}
if ((token.JsonTypeOf(L"access_token") != 1) || (token.StringOfEquals(L"access_token",L"",true) == true)) {
wprintf(L"An OAuth access token is required. Authorize or refresh the account first.\n");
return;
}
const wchar_t *mailbox = L"user@example.com";
CkImapW imap;
imap.put_Ssl(true);
imap.put_Port(993);
imap.put_RequireSslCertVerify(true);
imap.put_AuthMethod(L"XOAUTH2");
success = imap.Connect(L"imap.gmail.com");
if (success != true) {
wprintf(L"Could not establish the Gmail IMAP TLS connection.\n");
return;
}
success = imap.Login(mailbox,token.stringOf(L"access_token"));
if (success != true) {
imap.Disconnect();
wprintf(L"IMAP authentication failed. Check the mailbox, token scope, expiry, and Workspace policy.\n");
return;
}
// EXAMINE is read-only; no message is downloaded, marked read, moved, or deleted.
success = imap.ExamineMailbox(L"INBOX");
if (success != true) {
imap.Logout();
imap.Disconnect();
wprintf(L"Could not examine INBOX.\n");
return;
}
wprintf(L"Messages in INBOX: %d\n",imap.get_NumMessages());
success = imap.Logout();
imap.Disconnect();
if (success != true) {
wprintf(L"The read-only operation completed, but IMAP logout failed.\n");
}
}