How EspoCRM Google Workspace integration works for your sales team
Sales and service staff who live in Gmail and Google Calendar want CRM records and meetings to stay in step with their inboxes and schedules. The official Google Integration extension for EspoCRM addresses that need by connecting the CRM to Google through Google's OAuth flow, so each user authorizes access to their own Google account rather than sharing a single credential. The researched documentation covers three areas: syncing calendar events, pushing contacts to Google, and securing Gmail connections. Those are the capabilities this section describes, and you should confirm any other behavior, such as how Gmail messages are matched to records, directly against the current extension documentation before you promise it to your teams.
The connection depends on a few decisions made before any user clicks Connect. Your Google Cloud project, OAuth consent screen and OAuth client ID of type Web application determine which Google accounts can authorize and which redirect URI the browser returns to, so the EspoCRM URL must be final before the client is created. The docs also name three APIs to enable: the Google Calendar API for calendar sync, the Google People API for pushing contacts, and the Gmail API for secure Gmail connections. Enabling only the APIs for the features you intend to use keeps the consent request accurate for your users. Check that the curl, libxml and xml PHP extensions are present on the EspoCRM host, since the integration will not work without them.
Role permissions decide what each salesperson can sync. The integration acts on behalf of the signed-in user, so the scopes a user receives through their EspoCRM role determine whether calendar and contact sync is available to them at all. Plan the role matrix with your sales managers and service leads before rollout, and test with a non-admin account, because the security guidance for EspoCRM recommends keeping administrators off daily work. Ask your integrator or internal team to document which roles get calendar sync, which get contact push, and who approves changes to the Google project. Official Google Integration setup docs list the exact prerequisites to walk through with your team.
What you need before connecting EspoCRM to Google
Before any Google sync is configured, four things must line up: the EspoCRM host with its PHP extensions, a Google Cloud project with the right OAuth client, the Google APIs switched on, and a public HTTPS address that Google can redirect back to. Each card below is a checkpoint, and a gap at one of them usually shows up as a failed sign-in or a silent sync problem later.
EspoCRM instance and PHP extensions
The Google Integration needs the curl, libxml and xml PHP extensions on the server that runs EspoCRM. Check them on the actual host or container, not on a workstation, because a web process and a command-line process can load different extension sets. Confirm that the PHP version on your deployed release is in the supported range in the server configuration docs, since support depends on the EspoCRM release you run. Ask whether your hosting image already ships these extensions before the build starts.
Google Cloud project and OAuth client
Create or choose a Google Cloud project that the organization owns, then configure the OAuth consent screen and create an OAuth client ID of type Web application. Other client types will not match the EspoCRM setup steps. Keep the client secret in your secrets store, not in a shared spreadsheet, and record which Google account owns the project so access can be handed over later.
Calendar, People and Gmail APIs enabled
Enable the Google Calendar API for calendar sync, the Google People API for pushing contacts, and the Gmail API for secure Gmail connections. Each API is switched on separately in the project, and a missing one usually appears as an authorization or sync error only for the feature that depends on it. Note which features your teams actually need so you enable only what is in scope and can explain each API during review.
HTTPS public URL and redirect URI
The OAuth redirect URI registered in Google must match the address users reach EspoCRM on, including scheme, host, port and path. A mismatch is one of the most common causes of a failed connection. The address must be HTTPS and reachable from Google's sign-in flow, so a purely internal hostname needs a plan for how users will reach it. Decide the final domain before creating the OAuth client to avoid editing the redirect URI later.
Workspace admin approval for internal apps
If your Google Workspace domain marks the OAuth app as internal, only users in that domain can authorize it, and a Workspace administrator may need to approve the app or restrict third-party access. Ask your Google Workspace administrator early whether the app will be internal or external, who will approve it, and whether the consent screen needs a verified domain. Approval delays are a common reason go-live slips, so raise this before scheduling user training.
Version and docs confirmation
Exact EspoCRM and PHP version support, and the names of Google consent screen options, can change between releases and Google console versions. Confirm them against the current Google Integration docs for the release you deploy, and record the versions in your change ticket. This check belongs in the implementation plan, not in a one-time setup step, because upgrades can alter the prerequisites.
Configuring the Google Cloud project and EspoCRM step by step
This sequence takes a Google Cloud project from creation to a working EspoCRM Google Integration, so that a test user can complete consent and see the connection live. Each step ends with a check you can run before moving on.
Create or select a Google Cloud project
Decide which Google Cloud project will own the EspoCRM integration. Your Google Workspace administrator or a cloud administrator usually creates or selects it in the Google Cloud console, so that the OAuth client, API enablement and billing ownership sit with a team you control. Keep the project separate from unrelated experiments where you can, so that later changes to credentials and permissions are easy to audit. The step is done when the project appears in the console project selector with the name your team agreed on.
Configure the OAuth consent screen
In the project, open the OAuth consent screen and set the app name, support contact and authorized domains. Choose the user type that matches your tenant: internal applies when every user belongs to your Google Workspace organization, while external applies otherwise. List the scopes that EspoCRM will request for Calendar, People and Gmail access, and review them against the role permissions you plan to grant later. The step is done when the consent screen saves without validation errors and shows the publishing status you intended.
Enable the Calendar, People and Gmail APIs
In the API library for the project, enable the Google Calendar API, the Google People API and the Gmail API. The Calendar API supports calendar sync, the People API supports pushing contacts, and the Gmail API supports secure Gmail connections. Enable only these three unless your own design requires more. The step is done when each API shows as enabled on its overview page in the same project you configured in the earlier steps.
Create a Web application OAuth client
Under credentials, create an OAuth client ID and choose the Web application type, which is the type the EspoCRM Google Integration documentation requires. Give the client a name that identifies the EspoCRM instance, since you may later need to rotate or revoke it. Google shows the client ID and client secret once the client is created, so record them in your secrets store right away. The step is done when the client appears in the credentials list with the Web application type shown.
Register the EspoCRM redirect URI
Add the redirect URI that EspoCRM expects for the Google Integration to the authorized redirect URIs of the OAuth client. Build the value from the public address of your EspoCRM instance, using the exact scheme, host and path shown in the EspoCRM Google Integration setup documentation for your version. A mismatch between the registered URI and the one EspoCRM sends is the most common reason consent fails, so compare them character by character. The step is done when the saved client lists the redirect URI and it matches the value shown in EspoCRM.
Enter the client credentials in EspoCRM
Sign in to EspoCRM as an administrator who does not use this account for daily work, open the Google Integration settings, and enter the client ID and client secret. Confirm that the PHP prerequisites the documentation lists, including the curl, libxml and xml extensions, are present on the server before you save. Store the secret in the way your organization stores application secrets rather than in shared notes. The step is done when the settings save and the integration page shows the connection as ready to authorize.
Connect a test user and confirm consent
Choose a non-administrator test user whose role has the calendar and contacts permissions you intend to grant. Have that user open their own user settings, start the Google connection, and complete the consent screen with their Google account. Then check that a test calendar event and a test contact sync in the expected direction, and that the Gmail connection reports as active. The step is done when the test user sees a successful connection and the sync results match what your role design allows.
How the OAuth flow and sync scopes connect each user's account
Each EspoCRM user connects their own Google account, so calendar and contact sync runs per user and reflects the EspoCRM role permissions that user holds. The OAuth consent step is where a user grants the extension access to their Google data, so the consent screen configured in your Google Cloud project is the first screen every user sees. A user who can read fewer contacts or calendar entries in EspoCRM has less to push to Google. Read the Google Integration setup guide before you finalize role design, because those permissions decide what each person's sync can touch.
Three Google APIs back three different functions. The Google Calendar API supports calendar sync, the Google People API is required for pushing contacts from EspoCRM to Google, and the Gmail API supports secure Gmail connections. Enable all three in the same Google Cloud project that holds the OAuth client ID of type Web application, so the credentials you test with match the functions you planned. The People API matters most for contacts: if your plan includes pushing contacts and only the Calendar API is enabled, that function will not work. Confirm which roles can read and edit contacts and calendar entries in a test instance, since the sync acts with each user's permissions.
Sync direction and frequency are set in the extension's settings inside EspoCRM, so agree them with business owners before rollout. Confirm in the documentation and your pilot environment what each setting does to existing records, whether deletions propagate, and what happens to synced data when a user revokes access or leaves the company. Those answers determine whether the per-user model fits shared accounts, delegated assistants and departing staff. Record them alongside the role design, because a later change to a role will change what that user's sync sends.
Which EspoCRM roles and Google data map to each sync
This table maps each Google API used by the EspoCRM Google Integration to the EspoCRM data it touches and the role permissions a user needs for that sync. Read each row as a question to confirm in your instance: which role grants the access, and which Google account the sync is tied to. Exact permission labels can differ by version, so verify them in the deployed role editor before you assign them to users.
| Sync | EspoCRM data and role scopes to confirm | Google API and identity key |
|---|---|---|
| Calendar sync | Meeting: read and create (confirm exact labels in the role editor for your version) | Google Calendar API; each user's Google account is the identity key |
| Contacts push | Contact: read and create, plus any account or person scopes the sync reads | Google People API; each user's Google account is the identity key |
| Secure Gmail connection | The user's own email account record and the role that allows it to be created | Gmail API; the Google account signed in by that user is the identity key |
| Shared records | Team membership and record visibility settings, which limit which contacts and meetings a user can see | Applies to all three APIs; confirm that synced data stays within each user's team scope |
| Admin setup | Administrator access is needed to enable the integration, not to run per-user sync | Google Cloud project, OAuth client and enabled APIs; configured once by an administrator |
| Service or API users | Avoid assigning Google sync to API users or shared admin accounts | Sync should map to one named Google account per EspoCRM user for traceability |
Securing the Google connection and EspoCRM access
The Google connection gives EspoCRM access to calendars, contacts and mail, so its credentials and scopes deserve the same care as admin access to the CRM itself. The cards below cover the OAuth client, the consent screen, the Google Cloud project, and the EspoCRM accounts and login controls that sit around the integration.
Keep the OAuth client secret out of documents
The Google integration uses an OAuth client of type Web application, and its client secret lets whoever holds it act as your integration. Store the secret in a secrets manager or the server configuration with restricted file permissions, not in tickets, wiki pages or shared spreadsheets. Check who has seen the value during setup, and rotate it through Google Cloud if it was copied anywhere it should not have been.
Limit the consent screen to required scopes
Each API you enable and each scope the consent screen requests widens what EspoCRM can read on behalf of users. Request only the Calendar, People and Gmail access your chosen features need, and omit any capability you have not decided to use. Confirm the exact scopes the current EspoCRM release requests before publishing, because the list can change between versions.
Restrict the Google Cloud project owners
The Google Cloud project that holds the OAuth client should have a small, named set of owners, separate from people who administer EspoCRM day to day. Enforce multi-person control of the project and review its IAM roles on a schedule. Anyone who can edit the OAuth client or its redirect URIs can redirect tokens to a location you did not approve, so treat project access as a privileged path.
Keep redirect URIs exact
The redirect URIs registered on the OAuth client must match the EspoCRM address exactly, including scheme, host and path. Remove test or retired hostnames once the instance is live, and avoid wildcard-style entries where Google allows only exact values. A stale or broad redirect entry is the easiest way to leak authorization codes to an unintended endpoint.
Avoid admin accounts for daily work
The EspoCRM security docs recommend keeping administrators out of daily use, so the account that connects Google should be a named administrator used only for configuration. Sales and service users connect their own Google accounts under restricted roles. This limits what a compromised laptop or phishing click can reach in both EspoCRM and the connected mailbox and calendar.
Enforce 2FA and IP restrictions
The EspoCRM security docs recommend requiring two-factor authentication and restricting access by IP address. If you also use OpenID Connect sign-in, note that EspoCRM's own 2FA is not compatible with OIDC, so enforce MFA at the identity provider instead. Confirm which controls apply to each login path, including any fallback login method, before you rely on them.
Why the Google connection fails and how to fix it
This table lists the failures that most often stop EspoCRM from connecting to Google Workspace, with the cause and fix for each. Read it when a calendar or contacts sync stops working during setup or after go-live, and check the rows in order, since several failures share the same symptom.
| Failure | Likely cause | Fix |
|---|---|---|
| Redirect URI mismatch | The redirect URI registered on the Google OAuth client does not match the callback URL EspoCRM sends, often because of http versus https, a different hostname or a missing path. | Copy the exact redirect URI from the EspoCRM Google Integration settings into the OAuth client, then save and retry the connection. |
| Missing PHP extension | The server lacks the curl, libxml or xml PHP extension that the Google Integration requires, so the connection or XML parsing fails. | Install and enable curl, libxml and xml for the PHP version serving EspoCRM, restart the web server or PHP-FPM, and confirm them with phpinfo or the CLI. |
| API not enabled in the project | The Google Calendar, People or Gmail API is not enabled in the Google Cloud project that owns the OAuth client, so requests return access errors. | Enable each API the features need in the same project as the client ID: Calendar for calendar sync, People for pushing contacts, Gmail for secure Gmail connections. |
| Consent screen in testing mode | The OAuth consent screen is set to testing, so only listed test users can sign in and users outside that list are blocked. | Add each user who needs access as a test user, or move the app to production with the consent screen configured for your organization. Confirm the current publishing rules in Google's documentation. |
| User lacks the role scope | The EspoCRM role assigned to the user does not grant the calendar or contacts permissions, so sync runs but returns nothing or is refused. | Review the user's role and grant the calendar and contacts access it needs, then have the user reconnect Google from their own profile. |
| Expired or revoked tokens | The user revoked access in their Google account, changed their password in a way that invalidated the grant, or the refresh token expired because the app stayed in testing mode. | Have the user disconnect and reconnect the Google account, and check the consent screen status if tokens expire regularly across several users. |
Questions buyers ask about the EspoCRM Google integration
How much effort does the EspoCRM Google integration setup take?
The effort depends mostly on how many parts of the setup are new to your organization, not on the number of clicks in the console. The core work is a Google Cloud project, an OAuth consent screen, a Web application OAuth client with the correct redirect URI, and enabling the Google Calendar, People and Gmail APIs as the features you choose require them. On the EspoCRM side, the server needs the curl, libxml and xml PHP extensions. Each of these steps is small on its own, but a fixed-scope engagement lets you agree the exact list of users, features and environments before work starts, so the effort is known in writing rather than estimated from a call.
What makes the Google Workspace integration setup harder or slower?
Four factors usually decide how long the work takes:
- Number of users and the role design that controls which records each user can sync, since calendar and contact sync depend on the scopes users are granted.
- Google Workspace admin approval for the OAuth app and any internal or external consent settings your tenant enforces.
- PHP and hosting readiness, including whether the required extensions are already installed on the server running EspoCRM.
- Whether the instance is reachable at the exact address used in the redirect URI, especially behind a reverse proxy or in a test environment.
Confirm each of these early. Admin approval in particular can add waiting time that has nothing to do with the technical build.
Can our own team set up the EspoCRM Google integration without a partner?
Yes, a capable team can complete the setup alone, since the steps are documented and the official Google Integration is an extension you install into your own EspoCRM instance. What usually makes outside help worthwhile is the parts that are easy to get wrong: consent screen configuration, scope choices that match your data policy, role permissions that let the right users sync calendars and contacts without exposing other records, and a verification pass across test accounts. Ask yourself whether someone on your team has administrator rights in Google Workspace, can change the PHP configuration on the server, and has time to test with real user accounts before go-live.
What do we need to provide for the Google integration work?
Plan to provide the following before the work starts:
- Google Workspace administrator access, or a named admin who can create the Google Cloud project, configure the consent screen and approve the app for your domain.
- Administrative access to the EspoCRM server or hosting platform so the PHP extensions and the instance URL can be confirmed.
- A test plan with sample users, expected calendar and contact behavior, and the roles each group should receive.
- Named owners on both sides for approvals, sign-off on scopes and the final acceptance test.
If these owners are not identified, the engagement tends to pause at the first approval step, so agree them in the written scope.
How are changes to the Google integration handled after go-live?
Changes fall into three kinds: new users, changed role permissions, and changes to Google-side settings such as scopes, consent screen details or API enablement. New users usually need only role assignment and a sign-in test. Role or scope changes should go through the same test plan used at launch, because a permission change can widen or narrow what synced data a user sees. Ongoing support, upgrades and testing can be covered by a retainer, which is recurring, while the initial setup is normally a one-time fixed-scope piece of work. Ask any provider how changes are requested, tested and documented, and who approves them.
Which Google Workspace data does the integration expose, and how do we control it?
The integration reads and writes only what the Google APIs and the scopes you grant allow. Calendar sync uses the Google Calendar API, contact push uses the Google People API, and secure Gmail connections use the Gmail API. Control comes from three places: which APIs you enable in the Google Cloud project, which users receive the role permissions that expose the related EspoCRM entities, and how the OAuth consent screen describes the access to your staff. Review each scope with your security and privacy owners before rollout, and keep a record of what was approved.
Do we need to pay for EspoCRM or the Google integration to proceed?
EspoCRM is licensed under AGPL-3.0 and the open-source edition can be downloaded and self-hosted for free, according to the EspoCRM pricing page. The Google Integration is an official extension, and the Advanced Pack is included in EspoCRM Cloud plans, which is a separate choice from self-hosting. Confirm with the EspoCRM project which extension licensing applies to your edition before you plan the budget. Google Cloud and Workspace usage costs are set by your Google agreement, and DeployOpen does not publish a price list. A quote follows from the written scope.
What does a fixed-scope Google integration engagement include?
A fixed-scope engagement covers the agreed set of users, Google APIs, EspoCRM roles and environments, with deliverables and timelines written down before work starts. Typically this includes confirming prerequisites, creating the Google Cloud project and OAuth client, configuring the EspoCRM integration, designing role scopes for calendar and contact sync, running a test pass with named users, and handing over the configuration record. Anything outside that list, such as a second domain, additional services or new custom entities, is quoted as a change to the written scope rather than absorbed silently.
Official EspoCRM Google Integration documentation
The EspoCRM Google Integration setup documentation is the primary source for every step in this section, from creating the Google Cloud project to configuring the connector inside EspoCRM. Work from that page rather than from memory or from older blog posts, because the menu names in the Google Cloud console change over time and the connector's settings can differ between extension releases. Before you start, confirm which EspoCRM version and which Google Integration extension version your instance runs, then open the matching documentation. Your EspoCRM release line also affects which PHP version you need, so check the EspoCRM server configuration docs alongside the Google page.
Read the prerequisites section in full before you create any Google credentials. The documentation lists the PHP extensions the integration needs (curl, libxml and xml), the OAuth client type that must be created (a Web application), and the three Google APIs that must be enabled: the Calendar API for calendar sync, the People API for pushing contacts, and the Gmail API for secure Gmail connections. Confirm each extension on the server that actually runs PHP, since web and CLI PHP can load different configurations, and ask the administrator who owns the Google Cloud project to confirm which of the three APIs the business needs before enabling them. Each API you enable is a scope the connector can request, so enable only what your sync design requires.
Plan the redirect URI and the role scopes before go-live, because mismatches here are the most common reasons a connection fails. The redirect URI registered in Google must match the address your EspoCRM instance is served from, including the scheme and any path, so a test host, an internal name and a public domain each need their own registration. On the EspoCRM side, decide which roles may connect Google accounts and which users may sync calendars and contacts, and test with a non-administrator account. Keep the OAuth consent screen details, the audience setting and the list of users who will authorize the app in a change record, since anyone who later changes the project or the consent screen can break sync for every user.
How DeployOpen scopes and delivers EspoCRM Google Workspace integrations
DeployOpen plans, implements, hardens, documents and supports self-hosted open-source platforms inside your own infrastructure. For EspoCRM and Google Workspace, we start from the written scope of which users, calendars and contact sets must sync, then build the Google Cloud and EspoCRM configuration to match, with handover and optional retainer support after go-live.
How we scope
- Engagements are fixed-scope, with the Google accounts, sync direction and user groups agreed in writing before work starts.
- We confirm which Google services are in scope, including Calendar, People and Gmail, and which are not needed.
- We record the EspoCRM version, PHP version and extension prerequisites so the build matches your server before any changes.
How we build
- We create the Google Cloud project, OAuth consent screen and Web application client ID under your Google organization.
- We enable the Calendar, People and Gmail APIs and set the redirect URIs to match your EspoCRM domain and TLS setup.
- We configure role scopes so only the intended users can sync calendars and contacts, and test each path with sample accounts.
How we hand over
- You receive a written record of the Google project settings, redirect URIs, enabled APIs and EspoCRM role configuration.
- We document the steps to add a user to sync, the expected behavior on each sync path, and the known limits of the integration.
- We walk your administrators through the checks they will repeat after upgrades, credential changes or domain moves.
How we support
- Ongoing support, upgrades and continuous testing are available as retainers once the integration is live.
- Retainer work can cover re-checking OAuth settings after EspoCRM upgrades and Google policy or API changes.
- Quotes follow from the written scope, so ask for the Google, EspoCRM and testing items to be listed separately.
