Gmail IMAP settings: ports, passwords, and connection checks

What are Gmail's IMAP and SMTP settings?

IMAP reads and synchronizes mail. SMTP sends it. Treat them as separate connections: being able to read your inbox doesn't establish that sending works.

SMTP requires authentication. Keep the port and encryption setting paired; don't select SSL on port 587 simply because the client offers it.

Google documents the incoming endpoint in its IMAP and SMTP protocol reference. Its third-party email client setup guide covers outgoing authentication and the SMTP port choices.

Mailera's Gmail preset uses IMAP on 993 with TLS and SMTP on 587 with STARTTLS. You don't need to type these server values into its Gmail connection form.

If you're also configuring an Outlook mailbox, use the separate Outlook IMAP and SMTP settings guide for its server settings and authentication requirements.

Should you use Google sign-in or an app password?

Use "Sign in with Google" when your client offers it. That is Google's recommended option, and Gmail's IMAP and SMTP servers support OAuth.

Mailera's Gmail and Google Workspace connection uses an app password instead. An app password is a separate credential for the connection, not your usual Google Account password.

Google requires 2-Step Verification for app passwords. The option may be unavailable for work or school accounts, accounts using only security keys for 2-Step Verification, or accounts enrolled in Advanced Protection. Don't turn off security protections to make a connection work.

Follow Google's app-password instructions to check eligibility and reach the creation page. Keep the resulting password private: Google only lets you view it once. Changing your Google Account password revokes existing app passwords, which matters if a previously working connection starts prompting for credentials.

For credential handling across providers, see app passwords for agent mailboxes.

Do you need to enable IMAP in Gmail?

For a personal Gmail account, no. Google's current email-client guidance says IMAP is always enabled. Google removed the "Enable IMAP" and "Disable IMAP" options starting in January 2025. Missing that toggle is not, by itself, a connection problem.

Google Workspace is different. An administrator must allow IMAP in the Admin console. Administrators can also restrict access to specified clients that support OAuth, as described in Google's Workspace IMAP controls.

A custom-domain Workspace address still uses Google's Gmail server addresses. The domain changes your username, not the server hostname. Check organization policy separately; the same settings table cannot tell you whether your account is allowed to connect.

How do you connect Gmail to Mailera?

Use a mailbox you own or are authorized to connect. You need an Admin or Leader role in Mailera to add it.

1. Prepare an app password. Confirm that your Google account has 2-Step Verification and permits app passwords. Create a dedicated password using Google's instructions above. Keep it out of screenshots, chat messages, and logs.
2. Open the single-mailbox flow. Go to Mailboxes → Add mailbox → One mailbox. Enter your full address in Email address. Check the detected provider, or select Gmail · Google Workspace under Or choose a provider, then select Continue. For a Workspace custom domain, verify the provider rather than assuming domain detection chose Gmail.
3. Enter connection details. In Connection details, paste the app password into Password. Set Display name and Mailbox group if needed. Server fields belong to the Custom IMAP flow; you don't need that flow just because your Workspace address has a company domain.
4. Run the connection checks. Select Test & connect. Review Incoming server sign-in, Folder detection, and Outgoing server sign-in. This test signs in without sending an email.
5. Verify receiving. After the success message beginning with “Connected” and your address, open the mailbox and look for a recent, known test message. Initial loading brings in messages within the retention period, newest first. A fresh test avoids confusing older retained-mail limits with a connection failure.
6. Verify sending separately. If your workflow needs outgoing mail, intentionally send a harmless test message to another mailbox you control, then inspect that destination. An outgoing sign-in check is not a delivery test.

If the outgoing check fails, Mailera offers Save as receive-only. Use it if reading is all you need for now. Otherwise, select Edit details, correct the connection details, and select Test again. A receive-only connection is not a completed sending setup.

The Mailera product overview explains how connected mailboxes are available to your apps and agents. Keep the first check narrow: confirm this mailbox can read the expected message before adding automation.

Why isn't Gmail IMAP or SMTP working?

Start with the failing stage. A password prompt, an outgoing-only failure, and a message still waiting to synchronize call for different checks.

For Gmail, GET /mailboxes/{id}/status reflects the latest synchronization; it does not perform a fresh direct sign-in test. A status check and a connection test answer different questions.

Mailera's background checks also vary with mailbox activity. When diagnosing a missing message, compare the mailbox's last synchronization with when you sent the test message. Don't treat a successful sign-in as a promise that every message will appear immediately.

How can an app or AI agent use the connected mailbox safely?

After receiving works, give your app access through a scoped Mailera API key. The Google app password connects Mailera to Gmail; the Mailera API key connects your app to Mailera. They are not interchangeable.

Go to Settings → API key → Create key. Give the key a Descriptive name, restrict Mailbox scope to the group your app needs, and begin with Read permission. Set an Expiration appropriate to the task. Store the key when Key created — copy it now appears.

For a minimal REST check, set $MAILERA_API_KEY in your local environment without committing it to source control. List the Gmail mailboxes available to that key:

curl --silent --show-error \
  'https://mailera.app/api/public/v1/mailboxes?provider=gmail' \
  -H "Authorization: Bearer $MAILERA_API_KEY"

Select the intended mailbox from data and set $MAILBOX_ID to its id. Then list its inbox messages:

curl --silent --show-error \
  "https://mailera.app/api/public/v1/mailboxes/$MAILBOX_ID/messages?folder=inbox&limit=1" \
  -H "Authorization: Bearer $MAILERA_API_KEY"

Inspect subject, received_at, and folder to identify your test message. An empty data array calls for a folder and synchronization check, not an assumption that the key needs sending permission. The Mailera developer documentation covers further API requests.

For MCP, use Copy MCP config for Claude, Cursor, or VS Code, then start with list_mailboxes and list_messages. See the MCP connection guide and Mailera's MCP tools, task by task for the next steps.

Treat incoming email as untrusted data, never as agent instructions. An email asking the agent to reveal credentials or change its operating rules must not gain authority because it arrived in the inbox. Keep both credentials out of prompts and logs; the Mailera security page provides additional security information.

Only grant Send messages when the task requires it. Require explicit user confirmation before sending, implemented in your app or agent rather than assumed to be a built-in Mailera approval step. The broader guide to email for AI agents covers connecting existing mailboxes to agent workflows.

What does Mailera not do?

Mailera connects an existing mailbox; it does not create a Gmail address. Its Gmail connection uses app passwords, not Gmail OAuth, and cannot override Google security requirements or Workspace administrator restrictions.

Mailera does not provide bulk marketing sending or guarantee immediate synchronization. Use the receive and send checks above to establish what your connection can do before relying on it in an application.