How EspoCRM connects to Microsoft 365 through the Outlook Integration
Sales and service staff spend much of their day in Outlook, and they want calendar entries, contacts and email tied to the CRM records they work on. The supported way to do this in EspoCRM is the official Outlook Integration extension. It is not a custom connector. The extension authenticates against Microsoft through an app registration in Entra ID (formerly Azure Active Directory), and then calls Microsoft Graph using delegated permissions, which means each sync acts on behalf of the signed-in user and sees only what that user can see. Your Microsoft 365 administrator should expect to own the app registration, and your EspoCRM administrator should own the configuration and the scheduled jobs that keep data moving.
The permission set is small and optional by design. offline_access is mandatory, because it lets EspoCRM refresh a user's session without asking them to sign in again. The other four are chosen according to what each user needs: Calendars.ReadWrite for calendar sync, Contacts.ReadWrite for contacts, IMAP.AccessAsUser.All for reading mail and SMTP.Send for sending it. Grant only the scopes your sales and service roles actually use, because each one widens what the integration can read or change in a user's mailbox. Once the permissions are selected, Grant Admin Consent is required for Microsoft 365 users, so a tenant administrator must approve them before individual staff can connect. Plan that approval as a formal change in your tenant, with a named approver, rather than as a step the first user performs during rollout.
Before going live, confirm three things with your Microsoft 365 administrator: which mailboxes and accounts will connect, whether your tenant policy allows the chosen scopes, and who will renew the client secret. The EspoCRM docs note that if a never-expiring secret is not available, a two-year secret must be regenerated after two years, so record the expiry date and assign an owner. Calendar sync runs as the Outlook Calendar Sync scheduled job, which is every 10 minutes by default, so confirm that cron or your scheduler is running before you judge whether sync works. The EspoCRM Outlook Integration setup guide lists the exact redirect URI and permission steps to check against your tenant.
What you need before connecting EspoCRM to Outlook
Connecting EspoCRM to Microsoft 365 or Outlook.com touches the CRM version, the extension, the public address of the instance, the Azure tenant and the background job runner. Check each of these before you register anything, because a gap in one usually shows up as a failed consent or a calendar that never syncs.
EspoCRM release line and extension
Confirm which EspoCRM release your instance runs before you plan the integration. The current release line is 10.0.x, and the Outlook Integration is an official extension you install separately from the core product. Record the installed extension version alongside the core version so that a later upgrade does not break the connection without anyone noticing.
Reachable HTTPS address for the instance
Microsoft redirects users back to a Web redirect URI copied from EspoCRM, so the instance must be reachable at a stable HTTPS address that users' browsers can open. Confirm the public hostname, the certificate chain and any reverse proxy rules before you register the app. Changing the hostname later means updating the redirect URI in Entra ID as well.
Server requirements for the core product
The server must meet the EspoCRM server configuration requirements: PHP 8.3 to 8.5, MySQL 8.0 or newer, MariaDB 10.6 or newer, or PostgreSQL 15, on Apache, Nginx or IIS. Check these against your current host, since an instance that runs on an older PHP version may need work before the extension can be installed.
Scheduled jobs running on the server
Sync depends on background jobs. EspoCRM requires cron or a scheduled task to run its jobs, and the Outlook Calendar Sync job runs on that schedule. If cron is not running under the web server user, calendar events will not update even though the consent step appears to succeed. Confirm the schedule with your operations team and test that jobs execute before you go live.
Azure admin account and tenant type
Someone with rights to register applications in the Microsoft Entra admin center and grant admin consent must perform the setup. Decide first whether your users sign in through a Microsoft 365 tenant, which requires admin consent, or through individual Outlook.com accounts. Know the tenant ID and who approves tenant-wide permissions, because this decision sets who must be available during the build.
Configuring the Entra ID app and EspoCRM in sequence
This sequence takes you from an empty Entra ID tenant to a working Outlook Integration in EspoCRM, with consent granted, credentials stored and a test user's calendar confirmed as syncing. Each step leaves a visible check, so a failure can be traced to the step that caused it.
Copy the redirect URI from EspoCRM
Open the Outlook Integration settings in EspoCRM as an administrator and copy the Web redirect URI shown there. Keep the browser tab open, because the exact value must match the redirect configured in the app registration. Confirm that the URI begins with your EspoCRM site address and ends with the path EspoCRM displays, not a placeholder or a localhost address. If your EspoCRM instance is behind a reverse proxy, check that the public hostname is the one shown, since a mismatch here is a common cause of a failed sign-in later. The output of this step is a copied value you will paste into Entra ID.
Register the application in Entra ID
In the Azure Active Directory admin center, a user with rights to create app registrations opens the App registrations area and creates a new registration for EspoCRM. Set the platform to Web and paste the redirect URI copied in the previous step. Choose the account types that match your organization, whether a single tenant or a broader option, and record the application (client) ID shown on the overview page. The check for this step is an app registration that lists the correct redirect URI under the Web platform and an application ID you have saved for the next steps.
Create the client secret and record its expiry
Under Certificates and secrets, create a new client secret and copy its value immediately, because Entra ID does not display it again after you leave the page. Note the expiry date shown beside the secret in your change log or ticketing system. The EspoCRM documentation notes that if a never-expiring secret is not available, a two-year secret must be regenerated after two years, so confirm with your identity team which lifetime your tenant policy allows. The check is a secret entry with a recorded expiry date and the secret value stored in your approved secrets store, not in a shared document.
Select the Microsoft Graph delegated permissions
Under API permissions, add delegated permissions from Microsoft Graph. The offline_access permission is mandatory. Add Calendars.ReadWrite for calendar sync, Contacts.ReadWrite for contacts, and IMAP.AccessAsUser.All and SMTP.Send only if you want EspoCRM to use mailboxes through those protocols. Include only the permissions that match the features your team will use, because each added permission widens what the integration can read or send. The check is an API permissions list that shows each selected permission as delegated, with offline_access present and the optional permissions you intended.
Run Grant Admin Consent
Still under API permissions, a tenant administrator selects Grant admin consent for your organization. The EspoCRM documentation states that admin consent is required for Microsoft 365 users, so this step cannot be skipped by individual users signing in. Confirm that the status column for every permission changes to a granted state before you move on. If the button is unavailable or the status does not change, the signed-in account lacks the directory role needed, and the administrator should confirm that before retrying. The check is a granted consent status for all selected permissions.
Enter the client ID and secret in EspoCRM
Return to the Outlook Integration settings in EspoCRM and enter the application (client) ID and the client secret value saved in the earlier step. Save the settings, then complete the connection flow for a test user so EspoCRM can obtain a token. Record the test user's account in your test log. The check is a connected status for the test user in EspoCRM, with no authentication error recorded in the EspoCRM log for that request. If the sign-in returns an error, compare the redirect URI and secret value against Entra ID before changing anything else.
Enable the Outlook Calendar Sync job
In the EspoCRM administration area, open the scheduled jobs list and confirm that the Outlook Calendar Sync job is present and enabled. The EspoCRM documentation says this job runs every 10 minutes by default, so review that schedule against your change policy before you proceed. Make sure the server's cron entry or scheduled task is running, because EspoCRM background jobs depend on it. The check is an enabled job with its schedule visible in the list and cron running on the host.
Confirm a test user's calendar syncs
Create a meeting in the test user's Outlook calendar with a known subject, then wait for the scheduled job to run. Check the scheduled job log in EspoCRM for a run entry tied to that user, and confirm the meeting appears in the user's EspoCRM calendar. Then create a meeting in EspoCRM and check that it appears in Outlook. Keep both results in your test record, since they show the sync works in both directions for the permissions you selected. If the entry is missing, check the job log for a permission or consent error before changing the schedule.
Which Graph permissions each feature needs
The Outlook Integration asks Microsoft Graph for a set of delegated permissions, and the only one that is always required is offline_access. It lets EspoCRM keep a refresh token so that sync jobs can keep running after the signed-in user's session has ended. Without it, a calendar or mail connection would stop working as soon as the access token expired. The other four permissions are optional, and each one switches on a single feature. Calendars.ReadWrite enables calendar sync between EspoCRM meetings and the user's Outlook calendar. Contacts.ReadWrite enables contact sync. IMAP.AccessAsUser.All lets users read mail from their mailbox inside EspoCRM, and SMTP.Send lets them send mail from it. Request only what a team actually uses. Each extra permission widens what a connected account can reach, and it also adds a consent decision that someone has to make.
Plan the permission set by team before you open the Entra ID app registration. A sales team that needs meeting sync and contact sync does not need mail access, and a support team that sends mail through a shared mailbox may need IMAP.AccessAsUser.All and SMTP.Send but not calendar access. Document the list in your change record so that an admin can explain it later. When you change the scopes after launch, treat it as a consent change. Users and admins may need to re-consent, and you should confirm in the Entra ID consent settings that the updated permissions appear as granted. Check the Entra ID app registration after each change, not only the EspoCRM settings, because the two can drift apart.
Mail features depend on more than the Graph permission. The mailbox type (a Microsoft 365 user mailbox, a shared mailbox, or an Outlook.com account) and your tenant settings for IMAP, SMTP AUTH and admin consent can all block a feature even when the permission is granted. Confirm which of these applies to each mailbox against Microsoft's current documentation and your own tenant configuration, and test one account of each type before you roll out mail access. The EspoCRM setup guide, linked below, lists the redirect URI and consent steps that these permissions depend on.
How Outlook calendar, contacts and mail map to EspoCRM records
This table compares each Outlook data type with the EspoCRM entity or feature it lands in, the Microsoft Graph permission that enables it, the sync direction and who owns the result. Read it before granting consent, because each permission you approve widens what the integration can read or write. Field-level mapping should be confirmed in the Outlook Integration settings for your installed version.
| Outlook data | EspoCRM target | Permission and direction | Owner |
|---|---|---|---|
| Calendar events | Meetings linked to the user's calendar entries | Calendars.ReadWrite, two-way sync on the Outlook Calendar Sync job | Connecting user's own mailbox |
| Contacts | Contact records matched to the user's own address book | Contacts.ReadWrite, sync as configured in settings | Connecting user, with records assigned to that user or their team |
| Mailbox folders (IMAP) | Email records pulled into EspoCRM for the connected user | IMAP.AccessAsUser.All, inbound retrieval | Connecting user, subject to the user's access in EspoCRM |
| Sent mail (SMTP) | Outbound messages sent from the user's own address | SMTP.Send, outbound only | Connecting user, recorded against the sender |
| Shared mailboxes | Team or group email accounts, if configured | Confirm with your Microsoft 365 admin, as delegated access may differ | Team, configured by an administrator |
| User-level linking | Each user authorizes their own Microsoft account in EspoCRM | Delegated permissions granted per user after admin consent | Individual user, not a shared service account |
| Admin consent | Organization-wide approval for Microsoft 365 users | Grant Admin Consent is required for Microsoft 365 users | Microsoft 365 administrator |
| Field-level mapping | Which Outlook fields populate which EspoCRM fields | Confirm in the extension settings for the installed version | EspoCRM administrator |
Securing the Entra ID secret and the mail permissions
The Outlook connection rests on one Entra ID client secret and a set of delegated mail and calendar permissions, so the risk sits in who can grant them and when the secret expires. The cards below cover the secret lifecycle, consent scope, who may connect mailboxes, and the EspoCRM account and network controls that protect the integration.
Track the secret expiry date
The EspoCRM Outlook docs note that if a never-expiring secret is not available, a two-year secret must be regenerated after two years. When the secret expires, the Outlook connection stops working until a new secret is entered in EspoCRM. Record the expiry date at creation, set a reminder well before it, and name one owner who holds the renewal task. Confirm with your Microsoft 365 administrators which secret lifetimes your tenant policy allows.
Grant only the permissions you use
Offline_access is mandatory, but Calendars.ReadWrite, Contacts.ReadWrite, IMAP.AccessAsUser.All and SMTP.Send are optional. Add only the scopes your agreed use cases need, such as calendar sync without mail sending. Each extra scope widens what a compromised secret or a connected mailbox can reach, so review the list whenever the integration scope changes. Document which scopes were granted and why.
Control admin consent
Grant Admin Consent is required for Microsoft 365 users, so a tenant administrator must approve the permission set in the Entra ID portal. Treat that approval as a governance step: the administrator should see the exact scopes requested and the application owner recorded in your change log. Ask your Microsoft 365 team who approves consent for third-party applications and whether a consent workflow applies.
Restrict who can connect mailboxes
Any EspoCRM user with access to the Outlook settings may attempt to connect a personal mailbox, which can expose mail and calendar data beyond the sales team's need. Limit the relevant role permissions to the users who need them, and use teams to separate who sees synced items. Review the role assignments after reorganizations, since access rarely shrinks on its own.
Keep admins out of daily work
The EspoCRM security docs recommend avoiding admin accounts for daily work. Use a separate administrator account to create the app registration, rotate the secret, and change the integration settings, and keep day-to-day selling on a standard user account. This limits the blast radius if a browser session or workstation is compromised while an administrator is signed in.
Require 2FA and restrict by IP
The security docs recommend requiring two-factor authentication and restricting access by IP address. EspoCRM's own 2FA is not compatible with OIDC, so if you sign in through an identity provider, confirm that the provider enforces the second factor instead. Where your network allows it, limit access to the EspoCRM instance to known address ranges, and confirm with your security team how remote staff will reach it.
Why Outlook sync fails after setup and how to fix it
This table lists the failures teams hit most often after connecting EspoCRM to Microsoft 365 or Outlook.com, with the likely cause, the fix and the log or Entra ID record to check first. Work through the rows in order, since a missing permission or consent often looks like a mailbox or scheduling problem.
| Symptom | Likely cause and fix | Where to check |
|---|---|---|
| Redirect URI mismatch during sign-in | The Web redirect URI registered in Entra ID does not exactly match the one copied from EspoCRM. Correct the URI in the app registration so it matches character for character, including protocol and path. | Entra ID sign-in logs for the error code on the failed attempt, and the redirect URI on the app registration |
| Users see a consent prompt or access is denied in Microsoft 365 | Admin consent was not granted for the delegated permissions. A tenant administrator must select Grant Admin Consent, which the EspoCRM docs state is required for Microsoft 365 users. | Entra ID enterprise application permissions and consent status, and the sign-in log entry for the affected user |
| Sync stops after a period of working | The client secret has expired. If a never-expiring secret is not available, the two-year secret must be regenerated, then updated in EspoCRM. Confirm the expiry date in the app registration before go-live. | Certificates and secrets page of the app registration, and failed authentication entries in the sign-in log |
| Refresh tokens do not persist, so users must reconnect | The offline_access permission is missing. It is mandatory, and without it EspoCRM cannot keep access between sessions. Add it under delegated permissions, then grant consent again. | API permissions list on the app registration and the granted permissions shown for the user's consent record |
| Calendar or contacts never update, with no error in the UI | The Outlook Calendar Sync scheduled job is not running because cron or the scheduled task is not configured. The docs describe the job running every 10 minutes by default, so check that it executes at all. | Scheduled job status in the EspoCRM administration area and the EspoCRM log files on the server |
| Mailbox access denied for a personal account | The user signed in with a personal Outlook.com account, but the IMAP.AccessAsUser.All or SMTP.Send permissions were not granted for that account type or were not consented. Confirm which account type the app registration supports and which permissions the user has consented to. | Sign-in log for the personal account, the supported account types on the app registration, and the EspoCRM log for IMAP or SMTP errors |
Questions buyers ask before connecting EspoCRM to Microsoft 365
How long does it take to connect EspoCRM to Microsoft 365?
The setup time depends mostly on how many Microsoft services you enable and how quickly the right people approve the work. The core steps are an Entra ID app registration, copying a redirect URI from EspoCRM, choosing Microsoft Graph delegated permissions, granting admin consent, and then configuring each user's mailbox, calendar and contacts sync. The largest variables are how many users and mailboxes are involved, whether IMAP and SMTP are needed, and how long your Entra ID administrators take to review and consent. Ask any partner for a written scope that lists each permission and each user group, because that list is what drives the timeline in a fixed-scope quote.
Can an internal admin connect EspoCRM to Microsoft 365 alone?
Often yes, for a small deployment with one tenant and a clear list of permissions. The EspoCRM Outlook Integration documentation walks through the app registration and the permission choices, so an administrator comfortable with both EspoCRM and the Azure portal can follow it. The difficulty rises when the tenant has conditional access, restricted app consent, multiple domains, shared mailboxes or several EspoCRM instances. Most teams find that the Entra ID step is where a second pair of eyes helps, because a wrong permission or missing consent is hard to diagnose from the EspoCRM side.
What do we need from our Entra ID administrators?
You need someone with rights to register applications in Entra ID, and someone with rights to grant admin consent for the delegated permissions you choose. Admin consent is required for Microsoft 365 users, so the people who own consent policy must agree to the permission list before work starts. Plan for them to review each delegated permission, including IMAP.AccessAsUser.All and SMTP.Send if you enable mail, and to record who owns the app registration and its client secret. Confirm your tenant's app consent settings in advance, because a policy that blocks user consent can add a review step to every change.
How much effort does renewing the client secret take?
The effort is small each time but it recurs, and missing it stops the sync. The EspoCRM documentation notes that if a never-expiring secret is not available in your organization, a two-year secret must be regenerated after two years. Renewal means creating a new secret in the app registration, updating it in EspoCRM, and testing the connection. Record the expiry date in your change calendar, assign an owner, and confirm whether your tenant allows non-expiring secrets. If you use a partner for upkeep, ask whether secret renewal is covered by the retainer or billed as separate work.
Does Outlook.com work the same way as Microsoft 365?
The Outlook integration is designed around Microsoft Graph and the same app registration model, but the tenant context differs. Microsoft 365 users are governed by your organization's Entra ID tenant, where administrators control consent and policy. Outlook.com accounts are personal accounts, so there is no tenant admin to grant consent, and the permission and consent flow is handled by the user. Confirm the exact sign-in behavior, supported account types and permissions for your scenario in the EspoCRM Outlook Integration documentation before you promise the same experience to all users.
When is it worth bringing in a partner for this integration?
A partner is most useful when the tenant policy is strict, when several mailboxes or shared calendars are involved, when EspoCRM runs in a regulated environment that needs documented change control, or when no one on your team has time to own the secret lifecycle. DeployOpen implements and documents self-hosted open-source platforms in your own infrastructure, and most engagements are fixed-scope with the scope, deliverables and timeline agreed in writing before work starts. Ask for a quote built from a written list of permissions, users, mailboxes, testing steps and handover documentation, and compare it with the internal hours your Entra ID and EspoCRM administrators would need.
What drives the cost of the Microsoft 365 connection?
The cost comes from the people who do the work and the people who approve it. Internal cost is mostly administrator time across Entra ID and EspoCRM, plus testing with real users. Partner cost follows the written scope, so the number of permissions, user groups, mailboxes, integration points and environments all affect the quote. One-time work covers the registration, consent, configuration and testing. Recurring work covers secret renewal, permission reviews after Microsoft or EspoCRM changes, and any sync troubleshooting. When comparing quotes, ask which items are one-time, which recur, and who owns each recurring task after handover.
Running calendar sync on a schedule your teams can rely on
Calendar sync lag is a scheduling question as much as a connector question. The Outlook Calendar Sync scheduled job runs every 10 minutes by default, but that job only fires when EspoCRM's background jobs run, and those depend on cron or a scheduled task being configured on the server. If cron stops, meetings stop syncing without any error in the user interface, so the first check is always whether the scheduler itself is running. Confirm the cron entry exists under the account that runs EspoCRM, confirm the job is enabled in the scheduled jobs list, and confirm that the job's last run time moves forward. Ask your partner or internal team to document where this check lives so the on-call engineer can run it without the original builder.
Monitoring should cover three things: the job's run history, failed runs in the EspoCRM log, and the age of the Microsoft 365 secret. Watch the job for repeated failures after a password change, a consent withdrawal or a revoked token, because these look like sync gaps to users. Rotate the client secret before it expires. The EspoCRM docs note that if a never-expiring secret is not available, a two-year secret must be regenerated after two years, so put that date in your change calendar with an owner. Rotation means creating the new secret in Entra ID, updating the Outlook integration settings in EspoCRM, and confirming a successful sync before the old secret is removed.
Consent and testing need routine ownership too. When someone leaves or changes role, review who has consented to delegated permissions such as Calendars.ReadWrite and Contacts.ReadWrite, and remove access for accounts that no longer need it. Test calendar sync after each EspoCRM upgrade, since extensions and scheduled jobs can change behavior between versions. A short test with a dedicated pilot user, creating and editing one meeting in each direction and timing how long it takes to appear, gives you a baseline. Ask any partner quoting this work to include these recurring checks in the operating runbook and to state whether they are covered by a retainer or handed to your team.
How DeployOpen scopes and delivers the Outlook integration
The Outlook integration touches three places: the Microsoft Entra ID tenant, the EspoCRM instance and the users' mailboxes and calendars. DeployOpen starts with a written scope that names the features, users and admin roles, then configures and tests each part in order before handing over the operating runbook.
Written scope before any configuration
The scope names which features are in play (calendar, contacts, IMAP, SMTP), which user groups are included, and which mailboxes are in or out of sync. It also records whether the tenant is Microsoft 365 or Outlook.com, because admin consent applies to Microsoft 365 users. A quote follows from this written scope, and DeployOpen does not publish a price list, so the scope is the document to compare across bids.
Client admin steps in Entra ID
Your Entra ID administrators create the app registration, copy the Web redirect URI from EspoCRM, and grant the delegated Microsoft Graph permissions that the scope selects. They also run Grant Admin Consent. DeployOpen prepares the exact permission list in advance so your admins can review it against your own approval process before anything is changed in the tenant.
EspoCRM configuration and pilot testing
DeployOpen configures the Outlook Integration on your EspoCRM instance, sets the user-level sync options, and confirms the Outlook Calendar Sync scheduled job runs under cron. Testing starts with a pilot group of a few users, covering calendar events created in each direction, contact matching and email sending. Results from the pilot decide whether the wider rollout goes ahead.
Secret renewal calendar and runbook
If the client secret cannot be set to never expire, the renewal date becomes an operational deadline. DeployOpen hands over a renewal calendar with the expiry date, the owner who regenerates the secret, and the steps to update EspoCRM afterward. The runbook also lists the scheduled job, the consent state and how to remove a user's access when they leave.
Handover to your operations team
The handover covers the configured permissions, the redirect URI, the scheduled job settings and the pilot results, along with a short walkthrough for the team that will support users. Your team keeps the production tenant and the EspoCRM instance under its own accounts. DeployOpen does not hold standing admin rights after the handover unless the written scope says otherwise.
Optional retainer for upgrades and changes
Outlook integration behavior can change when EspoCRM or the extension is upgraded, and Microsoft permissions can change in your tenant over time. A retainer covers re-testing after upgrades, adjustments to permissions, and secret renewal support. Ask for the retainer terms in writing, including what is included in each period and how changes are scoped and priced.
