Connecting Gmail mailboxes to EspoCRM: IMAP, SMTP and OAuth

Why teams connect Gmail mailboxes to EspoCRM and what that connection does

Connecting a Google mailbox to EspoCRM lets sales and support staff keep working in Gmail while their conversations are linked to the accounts, contacts, leads and cases they relate to in the CRM. EspoCRM fetches mail from the account and sends replies from it, so the CRM record shows the correspondence that happened on that address. Without the link, the history stays in a personal inbox that colleagues cannot search and that is lost when someone leaves. The practical outcome is a shared record of customer contact that the people who need it can find, with the mailbox itself still managed by Google.

The first decision is whether the connection should belong to one person or to a group. A personal account is tied to one user, so that user sees the mail fetched for it and sends as themselves. A group account, such as a sales or support address, is shared by a team, and its mail is visible to the users and teams granted access to it. Choosing wrongly is hard to undo later, because moving mail and records between owners changes who can see past conversations. Map each address to an owner and a visibility rule before any settings are entered.

Confirm the exact screens, field names and fetch options against the current EspoCRM documentation for your version, since the email account settings and the Google integration have changed across releases. Check which connection method your Google Workspace administrator allows, which fetch-since date fits how much history the team needs to link, and whether the EspoCRM server can reach Google's mail services from your network. Treat the first connected mailbox as a test: send and receive a few messages, confirm they link to the right records, and check that other users cannot see what they should not.

IMAP and SMTP versus the Google integration: choosing a connection method

The manual route stores mail server settings directly on the EspoCRM email account. EspoCRM connects to Gmail's IMAP service to fetch messages and to its SMTP service to send them, using a username and a credential that you supply. This route does not depend on the Google extension, so it works without an OAuth client, but the credential it relies on is the part that needs the most care.

Administrator prerequisites: Your Workspace administrator must confirm that IMAP access is allowed for the users involved and that the account type can use the credential you plan to issue. Confirm the current Google requirements for app passwords and any 2-step verification dependency in your tenant, because these have changed over time.
Authentication: The credential is stored in EspoCRM and used on every fetch and send. Anyone with access to the stored credential can read the mailbox, so limit who can open the account settings.
Revocation: Revoking the credential in Google stops EspoCRM from fetching and sending, but you must update the settings in EspoCRM yourself. Nothing in EspoCRM reflects the revocation for you.
Best fit: A single user who needs a quick connection, or a small team that accepts manual credential rotation.
Ongoing effort: Expect to rotate the credential and recheck the settings whenever the user changes their password or the administrator changes the account policy.

Before you choose this route, ask your administrator whether the credential will be tied to a person or a service account, because that decision drives who must act when access changes.

Configuration options and when each fits

This table compares the main setup choices for Google mailboxes in EspoCRM: personal or group accounts, IMAP and SMTP or Google OAuth, how much mail history to fetch, and whether sending uses the inbox address. Read each row against who owns the mailbox and who manages the admin settings. The account type and fetch-since date deserve the most thought before users connect.

Choice	When it fits	What changes for users	What to check in admin settings
Personal account	One person works from their own Google mailbox and their correspondence belongs to them.	Each user sees and sends their own mail, and messages link to their own EspoCRM user.	Confirm each user connects only their own address and that no mailbox is attached to the wrong login.
Group account	A shared address such as sales or support that several people monitor and answer.	Mail arrives in one shared mailbox that the team can see, link to records and reply from.	Confirm the group account is set up as a group, the right teams have access and the permitted senders are listed.
IMAP and SMTP	You need a direct mail connection with server details and credentials, and your Google setup allows it.	Users or admins enter server details for each account, so setup is manual for every mailbox.	Confirm with Google which sign-in method your domain allows for IMAP and SMTP access before rollout.
Google OAuth through the Google integration	Google Workspace users should authorize access through Google's own consent screen.	Users approve access through a Google sign-in and do not enter mail server details.	Confirm the Google integration is installed, the OAuth client is configured and your Workspace admin allows the required access.
Recent fetch-since date	The team needs current conversations and does not need years of older correspondence.	Only mail from the chosen date forward is pulled in, so the timeline stays focused on current work.	Set the date deliberately for each account and agree who decides what happens to older mail.
Full history	The team is moving existing customer correspondence into records and needs older threads.	Older threads are fetched, so the first sync takes longer and records carry more history.	Ask how long the first sync will take, whether it runs as a background job and what storage it will use.
Same account for sending	The mailbox is a personal or small team address and replies should come from the address people see.	Replies and new messages go out under the same address that receives mail.	Confirm the send permission covers the address and that sent messages appear on the related records.
Separate sending address	Campaigns, system messages or a different identity need their own sender from the inbox.	Outgoing mail uses another identity, so recipients may reply to a different address than the one monitored.	Confirm reply-to behavior, that Google authorizes the sending address and that SPF, DKIM and DMARC are set with your DNS team.

Setup sequence for a Gmail or Google Workspace mailbox

This sequence takes a Google mailbox from an unconfigured account to a verified connection in EspoCRM, with each step closed by a check that proves mail flows in both directions and lands on the right records. Follow it in order, because ownership and account approval decisions made early determine what the later configuration steps can do.

Confirm the EspoCRM version and background jobs
The administrator confirms the EspoCRM version in use and checks that the server runs scheduled tasks. The server configuration documentation requires cron or a scheduled task for background jobs, and mailbox fetching depends on those jobs running. Confirm the PHP, database and web server combination against the supported list in the server configuration docs before going further. The step is done when a scheduled job is confirmed to run on the server, for example by checking the job log in the administration area after a few minutes. Ask the platform owner to record the version and the cron user so the mailbox setup can be repeated later.
Decide personal or group ownership
Decide whether the mailbox belongs to one person, such as an account executive, or to a shared address, such as sales or support. This decision controls who sees fetched messages, whether replies go out from a personal or shared identity, and whether the mailbox can later feed email-to-case. Personal accounts are tied to a user, while group accounts are set up for a team. Record the owner, the people who need access and the address each reply should come from. The step is done when this decision is written down and approved by the team lead responsible for the mailbox.
Prepare the Google account and admin approval
Work with the Google account owner or Google Workspace administrator to decide how EspoCRM will authenticate. For a Workspace tenant, the administrator may need to approve the connection or confirm which access rules apply before an OAuth grant succeeds, and IMAP and SMTP access must be permitted for the account. Confirm these settings in the Google Workspace admin console and in the mailbox's own settings, because Google's current requirements are not part of the researched facts for this page. The step is done when the account owner confirms in writing which method is allowed and any approval is recorded.
Enter IMAP and SMTP settings or complete OAuth
Create the mailbox in EspoCRM using the Google integration for OAuth, or enter IMAP and SMTP details manually where the chosen method requires it. Use the menu paths in the EspoCRM documentation for email accounts and the Google integration, and do not rely on memory of older screens. Store credentials through the method the security policy allows, and avoid using an administrator account for daily mailbox work. The step is done when the account saves and shows a connected or successful status, with no authentication error in the log.
Set the fetch-since date
Choose the fetch-since date that controls how far back EspoCRM imports messages. An early date pulls in a large history that may create noise and load on the server, while a recent date limits what can be linked to existing records. Agree the date with the team that owns the mailbox and confirm that the server's background jobs can process the import. The step is done when the date is saved and the first fetch completes, which you can confirm by checking that older messages from a known contact appear or are deliberately excluded.
Send a test message outbound
Send a test email from the connected mailbox to an address outside your organization that you control. Check that the message leaves with the expected sender name and address and that it appears in the sent folder of the Google mailbox. Also confirm it appears in the EspoCRM email list for that account. The step is done when the outbound test is received and the sent copy is visible in both places. If the sender address or display name is wrong, correct the account settings before continuing.
Receive and link a test message inbound
Send a reply to the test message from the external address, and confirm it arrives in the EspoCRM mailbox. Then check that it is linked to the correct record, such as the contact or lead that matches the sender's address. Test a second message from an address with no matching record to confirm it stays unlinked rather than attaching to the wrong account. Check the folder placement and notification behavior for personal or group ownership as decided earlier. The step is done when both inbound checks pass and the team confirms the linking behavior matches the agreed design.

How fetch-since dates control what enters EspoCRM

The fetch-since date decides how far back a Google mailbox is pulled into EspoCRM when it is first connected, so it is the single setting that determines how much existing conversation history lands in your CRM on day one. Choose it deliberately before you connect the account, because a long history is easy to import and hard to remove cleanly. Every message fetched becomes an email record, and each one is matched to contacts, accounts, leads and other records by address. A mailbox that has spent years exchanging mail with customers can therefore link old threads to records that no longer match, such as a contact who has changed employers, a shared address now owned by someone else, or a deal that closed long ago.

The trade-off is between a recent cutoff and migrating older conversations. A short window keeps the CRM focused on active relationships and limits the number of matches your team must review. A longer window preserves context for long sales cycles or support histories, but it increases fetch volume, the number of records created and the work needed to check the matches. Decide this with the sales and service leads before the connection, and record the decision with the mailbox owner. Older history that matters can often be brought in later through a controlled import rather than by extending the first fetch. Confirm with your version's documentation how the fetch-since date interacts with later fetches.

Large mailboxes depend on scheduled jobs running reliably, because EspoCRM fetches email in background processing that runs on the cron schedule your server is configured for. A first sync of a large history can take many runs to complete, and a stalled cron job will leave the mailbox partly imported without an obvious error in the user interface. Before you connect a full mailbox, confirm that the scheduled job runner is active and that you can see its progress. Test with a limited date range first, review the records created, and check how duplicates are handled in your version, including whether re-fetching the same messages creates copies or updates existing email records. Only widen the date range once that test result is clear.

Security considerations for Google mailbox connections

A Google mailbox connected to EspoCRM gives the CRM a standing path into staff email, so the connection needs the same access discipline as the mailbox itself. The cards below tie each risk to a control on the Google Workspace side and on the EspoCRM side, with the items to confirm in each.

Avoid storing mailbox passwords

A password-based IMAP and SMTP setup means EspoCRM holds a usable mailbox credential in its database. Prefer OAuth through the Google integration where it fits your setup, so the CRM holds a scoped token instead of the password. Ask your implementation team how EspoCRM stores the credential, who can read it in the database and backups, and what happens to it when a connection is removed. Confirm in Google Workspace that 2-Step Verification is enforced for the account used.

Keep admin accounts out of mail

Connecting a Google Workspace super admin account to EspoCRM gives the CRM access to mail for every user the admin can reach, and it makes that admin account a high-value target. Use a regular user account or a dedicated group mailbox for each connection. EspoCRM's security guidance also recommends avoiding admin accounts for daily work in the CRM itself. Confirm in Google Workspace which accounts hold admin roles and that none of them is used for the connection.

Revoke access when staff leave

A personal connection tied to an employee should end when that employee leaves, but a CRM connection is easy to forget because it runs in the background. Build an offboarding step that removes the user's EspoCRM connection, revokes the Google grant and disables the EspoCRM user. Check that personal accounts are not left behind on shared or group mailboxes. Confirm with Google Workspace how third-party app access is listed and revoked for each user, and document who performs the step.

Scope OAuth permissions narrowly

Each OAuth grant should request only the mail scopes the integration needs, and the consent screen should be reviewed by someone who knows what the CRM will read and send. Broad access to all mail, or to contacts and calendars the CRM does not use, widens the impact of a compromised token. Ask your implementation team to list the scopes requested, and confirm in Google Workspace which apps your domain has allowed and whether app access controls restrict unreviewed third-party apps.

Restrict EspoCRM access by IP

The EspoCRM admin panel and API hold the credentials that control mailbox connections, so a login from an unknown network is a serious event. Use the IP address restriction options in EspoCRM to limit access to office, VPN or known networks, and enforce 2FA for all users, as the EspoCRM security docs recommend. Note that EspoCRM's own 2FA is not compatible with OIDC sign-in, so confirm the chosen login method before you enforce it. Check the allowlist against the networks your staff actually use.

Limit who can change connections

Connection settings, fetch-since dates and sending accounts control what email enters the CRM and which address messages appear to come from. Restrict the roles that can create or edit email accounts to a small administrative group, and review changes to those settings. Confirm the EspoCRM role permissions for email account management and whether your audit or log retention captures changes made in the admin panel.

Questions teams ask before connecting Gmail to EspoCRM

What does it cost to connect Gmail to EspoCRM, and what drives the cost?

The cost depends on the written scope, which is set by how many mailboxes you connect, whether they are personal or group accounts, and whether mail history must move into EspoCRM. Work falls into a few parts: someone configures the Google side (Workspace admin settings and OAuth client setup), someone configures EspoCRM (accounts, teams, folders and fetch rules), someone tests each mailbox, and someone documents the result for your administrators. Each mailbox added and each historical import adds effort. DeployOpen does not publish prices, so ask for a fixed-scope quote that lists each of these parts, separates one-time setup from recurring work, and states which items your own Workspace admin must perform.

How long does it take to connect one mailbox compared with a shared group setup?

A single personal mailbox is the simplest case: one user, one account, one set of settings to verify. A shared group setup, such as sales@ or support@, takes longer because the design decisions come first: who owns the account, which team sees incoming mail, how replies are sent, and who receives notifications. Build time also grows with the number of accounts and with any requirement to import older mail. No duration figures are supplied for this work, so request a timeline in the written scope and ask the partner to name the assumptions behind it, such as the number of mailboxes and whether Workspace admin access is available on the first day.

What must our team provide before the work starts?

Plan to provide four things. First, Google Workspace admin access, or an admin who can create the OAuth client, approve the required API scopes and enable IMAP where needed. Second, decisions on ownership: which person or team owns each mailbox, and whether a shared mailbox is a group account. Third, test accounts and at least one test mailbox that can receive and send messages without touching live customer traffic. Fourth, a named contact who can approve configuration changes and confirm results. Ask the implementation partner to list these inputs in the written scope so that delays are visible before work starts.

Can a non-specialist administrator connect Gmail to EspoCRM alone?

A capable administrator with Google Workspace experience and EspoCRM admin rights can often connect a single personal mailbox by following the documentation, but the work has more failure points than it appears. The Google side involves OAuth consent, scopes and account policies, and the EspoCRM side involves SMTP and IMAP settings, fetch behavior and the scheduled jobs that pull mail. Group accounts add access design. Errors are often silent, so a mailbox may appear connected while mail is missing or replies come from the wrong address. Confirm with your own team whether someone can test, troubleshoot and document each step, and whether the Google and EspoCRM settings will be reviewed by a second person.

Should we use IMAP and SMTP settings or the Google integration?

Engineers should decide this from the authentication method, the mailbox type and the features they need. Manual IMAP and SMTP settings use credentials that must be managed carefully, and Google has tightened how sign-in works for third-party access, so confirm the current requirements in Google's own documentation before choosing. The Google integration uses OAuth, so it avoids storing a user password in EspoCRM. Verify which option your Workspace policies allow, which features the official Google extension provides in your EspoCRM version, and how each option handles group accounts. Record the choice in your design so the same approach is used for every mailbox.

Which security controls matter once Gmail is connected?

Start with the credentials and the accounts that hold them. Store OAuth tokens and any app passwords only where your policy allows, restrict which EspoCRM users can view or send through each account, and avoid using administrator accounts for daily mail work. The EspoCRM security documentation recommends enforcing a password policy, requiring two-factor authentication, and limiting authentication token lifetime. Confirm how these settings interact with OAuth and whether two-factor authentication is enforced at the Google layer instead. Review the access list for every group account whenever someone changes role, and document who can revoke a connection.

What ongoing work follows the initial connection?

Ongoing work includes rotating credentials or re-authorizing OAuth connections when policies change, checking that scheduled jobs that fetch and send mail keep running, reviewing mailbox access as staff join and leave, and watching logs for fetch or send failures. Plan for a regular check after Google policy changes and after each EspoCRM upgrade, since upgrades can change mail behavior. EspoCRM relies on cron or a scheduled task for background work, so monitoring of that process is part of operations. Ask for a handover that names who checks these items, how often, and how failures are escalated. Support and maintenance can be scoped as a retainer if your team prefers an external owner.

What DeployOpen confirms before connecting your mailboxes

Before any Google mailbox is connected, a fixed-scope engagement fixes the decisions that are expensive to change later: which mailboxes are in scope, who owns each one, how EspoCRM authenticates to Google, and how far back email history is fetched. These points go into the written scope so that the client's Google administrator and the EspoCRM administrator have the same picture before any credential is created. The mailbox list names each address, whether it is a personal account or a group account, the users or teams who will see its messages, and whether it will also send outbound mail from EspoCRM. Each of these choices changes which settings and permissions the build needs.

The connection method is confirmed next. The written scope states whether each account uses IMAP and SMTP with an app-specific credential, or OAuth through the Google integration, and which Google Workspace administrator actions are required, such as allowing the EspoCRM application and granting the scopes it requests. It also records the fetch-since date for each account, because a date set too early imports years of mail that the team never needs in the CRM. The engagement should also name who holds the Google credentials after handover and how they are rotated, since a personal password reset can silently stop every fetch that depends on it.

Testing is written into the scope as well. Typical checks include a test fetch into a non-production record set, a sent message from each sending address, confirmation that replies thread to the correct record, and a review of which users can read which mailbox. The handover document lists the final settings, the owners of each account and the checks the client's team should repeat after a Google or EspoCRM upgrade. Confirm with your provider which of these checks are included in the fixed price and which are billed separately.

How DeployOpen scopes and supports EspoCRM mailbox connections

DeployOpen plans, implements, documents and supports self-hosted open-source platforms inside your own infrastructure, including EspoCRM. For Gmail and Google Workspace mailboxes, we agree the mailbox model, authentication method and sync rules in writing first, then build and test the connection in your environment before handover.

How we scope

Inventory which Google mailboxes, group addresses and users need to connect, and who will see each inbox
Decide between personal and group accounts, and record the fetch-since date each mailbox will use
Agree in writing which Google Cloud and Workspace settings your administrators must provide before work starts

How we build

Configure IMAP and SMTP or the Google integration on a test instance, following your chosen authentication method
Test fetching, sending, linking emails to records and reply behavior with real sample mailboxes you provide
Document access permissions, sync settings and known limits so administrators can repeat the setup safely

How we hand over

Provide a written runbook covering each connected account, its owner, its settings and its recovery steps
Walk your administrators through adding a mailbox, rotating credentials and revoking access
Confirm the handover checklist with your team before the engagement closes under the agreed fixed scope

How we support

Offer ongoing support, upgrades and continuous testing as a retainer if your team wants help after handover
Review connection health, authentication changes and EspoCRM version updates when your retainer covers them
Ask your quote to separate one-time build work from any recurring support so costs stay visible

Connecting Gmail and Google Workspace mailboxes to EspoCRM

Why teams connect Gmail mailboxes to EspoCRM and what that connection does

IMAP and SMTP versus the Google integration: choosing a connection method

Configuration options and when each fits

Setup sequence for a Gmail or Google Workspace mailbox

Confirm the EspoCRM version and background jobs

Decide personal or group ownership

Prepare the Google account and admin approval

Enter IMAP and SMTP settings or complete OAuth

Set the fetch-since date

Send a test message outbound

Receive and link a test message inbound