Set up Gmail in NodeMail on your Mac

Before you begin

• Use a Mac supported by the current NodeMail release and a Gmail account you control.
• Your Google account must allow app passwords and have 2-Step Verification enabled. Check organization restrictions before starting.
• Choose a working connection for this mailbox. Gmail setup in the built-in browser also requires the Browser Runtime to be ready.

Set up in NodeMail

1. Open NodeMail Settings and add an email account. Enter the full Gmail address and select the Gmail preset; leave Authentication on Password / App Password.
2. Choose Direct, Clash Node or Manual SOCKS5 in Connection. If you use a proxy, select its existing profile and, where applicable, the desired node.
3. Click Set up Gmail in fingerprint browser. Sign in to the Google account matching the address in the form. Use Google security settings if you need to configure 2-Step Verification.
4. Open Google’s App passwords page and create an app password for NodeMail. Select only the generated 16-character password in the browser.
5. Return to NodeMail and click Import selected app password. Alternatively, enter the generated password in App Password. Importing the selection does not save the account.
6. Click Save Account and wait for connection verification. Open the inbox, then send a test message to an address you control to check outgoing mail separately.

Server settings

What the server table means

The table shows NodeMail’s Gmail defaults. Receiving and sending are separate connections, so successful browser sign-in or inbox access does not establish that SMTP works.

For a Workspace address, confirm IMAP access and the permitted authentication method with your administrator. A custom email domain alone does not identify its mail service.

Keep the credential with the mailbox

Use a separate app password for this client so you can revoke it without changing unrelated clients. Never include the password, OAuth tokens or recovery codes in a support request.

NodeMail’s website account manages the app’s plan and sign-in. It does not replace the Gmail account added to the desktop app.

Troubleshooting

App passwords is unavailable

Check your Google account’s security and organization settings. Advanced Protection, security-key-only verification or administrator policy can prevent this method. Google recommends OAuth-capable clients; NodeMail’s current Gmail setup cannot override a restriction.

Import rejects the selection

Open App passwords in this mailbox’s NodeMail browser and select only the generated password. The account address must still match the form. You can enter the password manually instead; do not use a verification or recovery code.

An existing connection stops working

Changing your Google password revokes app passwords. If yours was revoked, generate a replacement and update the saved account. For a timeout, inspect the selected route and IMAP/SMTP ports before changing credentials.

Browser setup does not open

Check Browser Runtime in Settings and allow installation to finish. Confirm the selected proxy still exists and is reachable, then retry without adding a duplicate account.

Related guides

• Choose the connection for each mailbox
• Manage multiple mailboxes in one Mac workspace
• Add Outlook or Hotmail with Microsoft OAuth
• All mailbox setup guides

References and maintenance

• Google: App passwords
• Google Workspace: Third-party email clients

NodeMail setup-guide maintainer

2026-09-12 — Added the Gmail guide on September 12, 2026; checked the app-password flow, client defaults and official references.

Found a changed setting? Contact support@nodemail.app.