Gmail SMTP, IMAP, and POP3 Guide
Gmail supports SMTP for sending email, IMAP for working with messages and labels, and POP3 for downloading available mail. Use Chilkat.MailMan for SMTP and POP3, Chilkat.Imap for IMAP, and Chilkat.Email to hold a message, including its headers, body, and attachments.
Choose a language to update all 14 example links below. Each link opens the complete source code in that language. The guide text and property names stay the same.
Use these connection settings and enable RequireSslCertVerify to verify the server certificate. Implicit TLS starts when the connection opens; STARTTLS upgrades the SMTP connection before authentication. Google protocol documentation.
| Protocol | Server | Port | Chilkat settings |
|---|---|---|---|
| SMTP | smtp.gmail.com | 587 | StartTLS=true, SmtpSsl=false |
| SMTP alternative | smtp.gmail.com | 465 | SmtpSsl=true, StartTLS=false |
| IMAP | imap.gmail.com | 993 | Ssl=true |
| POP3 | pop.gmail.com | 995 | PopSsl=true |
Authorization
Authorize once, then refresh
The ordinary OAuth scope for all three protocols is https://mail.google.com/. A single grant for the mailbox can be used with SMTP, IMAP, and POP3. Narrower Gmail REST scopes such as gmail.send and gmail.readonly do not authorize these protocols. Public apps requesting the full-mail scope must meet Google’s verification and user-data requirements. Gmail scopes and XOAUTH2.
Create an OAuth client of type Desktop app in Google Cloud for the interactive setup example. It opens the system browser, uses a loopback callback and PKCE, and requests offline access. The browser and application run on the same computer. After consent, it saves the token response in gmail-mail-token.json in a private working directory. Keep separate credentials for each account and OAuth client. Google desktop OAuth setup.
Subsequent runs refresh the saved grant without prompting again. Use the same client ID and secret, preserve the previous refresh token when Google omits it, and track the new token lifetime. Revoked grants need fresh consent. External apps in Testing normally receive refresh tokens that expire after seven days when requesting the mail scope. Protect token files and avoid printing credentials or authentication session logs. Google token lifetimes.
- Gmail SMTP, IMAP, and POP3: Obtain an OAuth2 Token
- Gmail SMTP, IMAP, and POP3: Refresh an OAuth2 Token
App passwords
OAuth2 is the preferred approach. An eligible account can instead use a generated app password after enabling 2-Step Verification. Availability depends on account and organization policy; a normal Google account password will not work. The example authenticates to a selected protocol and disconnects without sending or downloading messages. Google app-password requirements.
SMTP
Send with the mailbox’s access token
Set SmtpUsername to the authorized mailbox and OAuth2AccessToken to its current token. Leave SmtpPassword empty. Chilkat performs the XOAUTH2 exchange and SendEmail submits the composed Email.
The SMTP examples send a real message. Use a recipient you control. The From address should be the mailbox or an authorized Gmail send-as identity. Gmail normally saves SMTP submissions in Sent, so avoid adding a second copy through IMAP. SMTP acceptance means Gmail accepted responsibility for delivery; it does not prove inbox delivery. Sending limits still apply, and an interrupted submission can require checking the outcome before retrying.
Send as a Workspace user through delegation
A Workspace administrator can authorize a service account’s numeric OAuth client ID for the full-mail scope using domain-wide delegation. AuthGoogle uses the JSON private key to obtain a token for the user named by SubEmailAddress. Use that same mailbox for SMTP authentication. This signed JWT grant works for delegated Workspace mailboxes; a service account has no Gmail mailbox of its own. Obtain a new short-lived token when needed and protect the key. Google service-account delegation.
IMAP
Connect and find Gmail folders
Set AuthMethod="XOAUTH2" and pass the mailbox and access token to Login. Use ExamineMailbox for read-only access and SelectMailbox when making changes. Log out and disconnect when finished; refresh and reconnect when a token or session expires.
Personal Gmail accounts have IMAP enabled automatically. Workspace administrators can restrict access. Gmail exposes labels as folders, and folder names can be localized. Discover All Mail, Sent, Spam, and Trash through LIST special-use attributes with MbxList; use the returned names in subsequent calls. Current Gmail client-access settings.
Search and work with labels
QueryMbx accepts Gmail search syntax through X-GM-RAW, including operators such as from: and has:attachment. Results belong to the selected mailbox. The search example discovers All Mail, which normally includes inbox and archived mail but excludes Spam and Trash.
X-GM-LABELS reads or changes a message’s labels. The label example defaults to reading; choose add or remove to change one custom label. It accepts printable ASCII custom labels, quotes them for IMAP, and displays the returned label-list syntax. Raw non-ASCII label arguments require modified UTF-7 encoding. The examples check the tagged server status as well as transport completion, because a completed raw exchange can return NO or BAD.
Identify the same message across folders
X-GM-MSGID identifies a Gmail message across labels; X-GM-THRID groups messages into a Gmail conversation. Keep both as strings. IMAP UIDs are different: they belong to a particular mailbox and UIDVALIDITY. The example samples INBOX and All Mail and avoids counting the same Gmail message twice. Its decimal IDs also differ in representation from Gmail REST’s hexadecimal ID strings. Gmail IMAP extensions.
Archive or move to Trash
This example changes one message in INBOX. It finds that message by Gmail ID and uses MoveMessages with the server’s MOVE capability. Moving to All Mail archives it; moving to Trash puts it in the deletion workflow. Gmail normally removes messages permanently after 30 days in Trash. The example discovers the destination folder and avoids a broad EXPUNGE affecting unrelated messages.
Workspace administrative IMAP access
The delegated https://www.googleapis.com/auth/gmail.imap_admin scope is specific to Workspace IMAP. It includes labels hidden by the user’s Show in IMAP setting and messages excluded by folder-size limits. An administrator must authorize this scope for the service account. It does not authorize SMTP or POP3 and does not apply to personal Gmail accounts. The example lists folders and examines INBOX without changing messages. Delegated IMAP scope.
POP3
Check the mail currently available through POP
Enable POP in Gmail settings and choose its delivery window and what happens to Gmail’s copy after access. For OAuth2, set PopUsername to the mailbox, leave PopPassword empty, and set OAuth2AccessToken. The authentication example checks the available count without retrieving or deleting mail. Delivery history and batching mean this count is not the whole Gmail mailbox.
Use recent mode and avoid duplicate downloads
Recent mode uses recent: before the POP username and exposes a rolling window of roughly 30 days. The download example uses an eligible account’s app password, leaves mail on the server, and tracks opaque UIDL strings using deterministic local filenames. It writes a complete MIME message to a temporary file before committing the final file. A later run skips committed downloads. Keep the private directory dedicated to this downloader and run one writer at a time. Gmail POP settings and recent mode.
Gmail’s removal of “Check mail from other accounts” concerns Gmail fetching mail from external providers. Applications can still connect to Gmail’s own POP and IMAP servers. Google’s POP changes FAQ.