How to Add Gmail to Apple Mail on Mac (Without Breakage)

Adding Gmail to Apple Mail on Mac is not a matter of typing your Gmail address and password into a settings panel. Google disabled basic password authentication for IMAP access in 2022, so the correct path for a personal Gmail account runs through an OAuth browser sign-in — you authorize Apple Mail through Google's own sign-in page, and Google issues a token rather than accepting a password. Understanding this is how to add Gmail to Apple Mail on Mac without triggering the repeated-sign-in loop that catches most users.

There are two supported routes. The first — and the one that avoids most problems — is System Settings > Internet Accounts, which handles the OAuth handshake automatically and stores the token in macOS Keychain. The second is a manual IMAP configuration using an app-specific password generated from your Google account. Manual IMAP is more fragile because it uses a static credential that must be updated every time you rotate the app-specific password, and Google can revoke it independently. Start with Internet Accounts; manual IMAP is a fallback for edge cases and Google Workspace environments with restrictive admin policy.

This guide covers the setup steps, what changes between personal Gmail and Google Workspace accounts, a platform-differences table across macOS versions, and a structured fix for each failure mode — including the password-not-accepted error, the repeated-sign-in prompt, and the duplicate-messages symptom that appears when Gmail's All Mail folder mapping conflicts with Apple Mail's defaults.

Before you start#

A few conditions determine which setup path works and what to expect during the process. Check these before opening System Settings.

• macOS Ventura 13 or later: the account setup lives at System Settings > Internet Accounts. On macOS Monterey 12 and earlier it is at System Preferences > Internet Accounts — the same flow, different app name.
• A Google account in good standing: the sign-in prompt opens Google's own authentication page in your default browser. If the account is suspended, under a security hold, or subject to an admin lockout, the OAuth flow fails at the browser step rather than inside Mail.
• Google Workspace accounts need admin approval first: a Workspace admin controls whether IMAP is enabled at the domain level and whether third-party mail clients are permitted. If your organization has restricted access to third-party apps or uses a context-aware access policy, the connection can be blocked even after a successful browser sign-in. Confirm IMAP access is enabled in the Google Admin console before adding the account on macOS.
• Two-factor authentication affects the manual IMAP path only: if you are taking the manual IMAP route rather than Internet Accounts, you cannot use your Google account password directly. Google requires an app-specific password for any client connecting via IMAP when two-factor authentication is active. Generate one at myaccount.google.com > Security > App Passwords.

How to add Gmail to Apple Mail on Mac#

The Internet Accounts method completes in under two minutes for a personal Gmail account and does not require enabling anything in Gmail settings ahead of time. The steps below apply to macOS Ventura 13 and later. On Monterey, replace 'System Settings' with 'System Preferences' throughout.

1. 1

   Open System Settings and navigate to Internet Accounts

   Click the Apple menu in the top-left corner and select System Settings. In the sidebar, scroll down to Internet Accounts and click it. The pane lists any accounts already configured on this Mac. On macOS Monterey or earlier, open System Preferences instead and click Internet Accounts.

2. 2

   Click Add Account and select Google

   Click Add Account at the bottom of the account list. A sheet appears showing supported account types: iCloud, Microsoft Exchange, Google, Yahoo, AOL, and other. Click Google. macOS opens a sheet warning that sign-in will happen in your default browser — click Open Browser.

3. 3

   Complete the Google sign-in in your browser

   Your default browser opens to Google's sign-in page. Enter the Gmail address and password for the account you want to add. If the account has two-factor authentication active, complete the second-factor step. Google then asks which permissions to grant Apple Mail — allow access to Gmail. Click Continue or Allow. The browser displays a confirmation that authorization is complete and prompts you to return to System Settings.

4. 4

   Choose which Google services to sync in Mail

   Back in System Settings, a list appears showing the Google services available to sync: Mail, Contacts, Calendars, and Notes. Toggle Mail on. Leave the others off if you do not want contacts or calendar events from this Google account appearing in the corresponding macOS apps. Click Done.

5. 5

   Open Apple Mail and wait for the initial sync

   Open Mail from the Dock or Applications folder. The Gmail account appears in the sidebar under its address. Mail immediately begins fetching messages from the inbox and All Mail. The first sync can take several minutes for a large mailbox — the status bar at the bottom of the Mail window shows sync progress. New messages arrive in real time once the initial fetch completes.

6. 6

   Verify the account is connected in Mail Settings

   Press Command-Comma to open Mail Settings, then click the Accounts tab. The Gmail account should appear with a green connected status. If a yellow or red warning appears instead, the OAuth token was not stored correctly — remove the account from System Settings > Internet Accounts and add it again. The token issue resolves on a fresh authorization more reliably than attempting to repair the stored credential.

How Gmail accounts behave differently across macOS versions and account types#

The setup steps above are consistent across recent macOS versions, but the behavior after setup — folder mapping, connection method, and admin policy enforcement — varies by account type and macOS release. The table below captures the differences most likely to produce a broken or unexpected setup.

What to do when the Gmail connection does not work#

The most common failure modes after adding a Gmail account to Apple Mail are a persistent password prompt, a connection error that clears briefly and returns, and duplicate messages appearing in the inbox. Each has a distinct cause and a specific fix.

How to remove and re-add a Gmail account in Apple Mail#

Removing and re-adding an account is the fastest fix for a persistent sign-in prompt, a revoked token, or an account that appears connected but stops fetching mail. The process takes about two minutes and does not delete any messages from Gmail — it only removes the local IMAP connection and the cached headers Apple Mail stores on the Mac.

1. 1

   Open System Settings and click Internet Accounts

   On macOS Ventura 13 and later, go to System Settings > Internet Accounts. On Monterey 12 and earlier, go to System Preferences > Internet Accounts. The list of configured accounts appears in the pane on the right.

2. 2

   Select the Gmail account and remove it

   Click the Gmail account you want to remove. A Remove Account button or a minus sign appears at the bottom of the account list. Click it. macOS asks you to confirm — click Remove. The account disappears from the list and from Apple Mail's sidebar within a few seconds.

3. 3

   Wait 30 seconds, then add the account again

   Waiting briefly lets macOS clear the cached Keychain entry for the removed account. Then click Add Account, select Google, and complete the browser sign-in as described in the setup steps above. Google issues a new OAuth token during this flow.

4. 4

   Verify the connection status in Mail Settings

   Open Mail > Settings > Accounts and confirm the re-added Gmail account shows a green connected status. If it shows a warning immediately, the Workspace admin may be blocking the connection at the domain level — that is a policy issue outside Apple Mail's settings and requires an admin change on the Google side.

A faster way to manage Gmail alongside your other accounts#

The steps above get Gmail working in Apple Mail reliably. What they do not solve is the recurrence pattern: every time Google revokes the OAuth token — and it does, on security events, idle periods, and admin policy changes — the same removal-and-re-add cycle runs again on every Mac, iPhone, and iPad where the account is configured. The revocation is per-account; the consequence is per-device.

We build AI Emaily, an AI-native email client that connects Gmail, Outlook, and IMAP through server-side sync rather than per-device IMAP sessions. When a Gmail token is revoked, reconnecting it in AI Emaily fixes all surfaces at once — there is no device-by-device re-authorization cycle. It also handles the IMAP session ceiling differently: because sync runs server-side rather than in the client, the simultaneous-session count does not grow with every device you open the app on. A 7-day free trial is available on the Pro plan (card required, cancel before day 7 at no cost) if you want to check whether that architecture difference matters for how you actually work.