How ERPNext email with Microsoft 365 using OAuth works
Your ERPNext site needs to send and receive mail through a Microsoft 365 mailbox, and your security team does not want a mailbox password stored in the site. The supported approach is Frappe's Microsoft email OAuth flow, which replaces a stored password with an OAuth grant between your site and Microsoft. The flow has three linked pieces: a Connected App inside the ERPNext site, an app registration in Microsoft Entra ID, and the application (client) ID copied from Entra ID back into the Connected App. Frappe's documentation on Microsoft email OAuth is the reference for the exact field names and screens in your Frappe version, so confirm them there before you start.
The order matters. You create the Connected App first so that ERPNext generates the redirect URI for your site. You then register the app in Microsoft Entra ID, add that redirect URI under the Web platform, and copy the application (client) ID from the registration into the Connected App. The redirect URI must match your site's address exactly, including the scheme and path, so a change to the domain or TLS setup later means updating the registration as well. Ask your Microsoft 365 administrator who can create app registrations and grant consent in your tenant, because that permission is often restricted and can add days to the work if it is not sorted out early.
Before go-live, confirm three things with the people who own each system: which mailbox the site will use, whether your tenant requires admin consent for the permissions the app requests, and who will hold the registration and its credentials as your organization changes. Test both sending and receiving from the mailbox, because a working outbound test does not prove that inbound mail is being fetched. Record the Connected App settings and the Entra ID registration in your change log so that a future redirect URI change, secret rotation or site migration does not break email silently.
What you need before you start
Most delays in this setup come from missing access rather than from configuration. Confirm the mailbox, the Entra ID rights, the approval path and the site details before you open either admin console, because the Connected App and the Entra ID registration must reference each other.
Microsoft 365 or Outlook mailbox
Identify the exact mailbox ERPNext will send from and receive into, such as a shared sales or support address or a dedicated system account. Confirm that the mailbox is licensed, not disabled, and that it can sign in with the modern authentication flow used by Microsoft 365. Decide now whether ERPNext will send as this mailbox or on its behalf, because that choice affects the permissions you request later and how replies appear to customers.
Entra ID tenant and app registration rights
You need an account in the Microsoft Entra ID tenant that owns the mailbox, with permission to register applications. Many organizations restrict this to administrators or to a delegated group, so check the tenant's user settings before planning the change. Without this right, the Entra ID app registration step cannot be completed, and the Connected App in ERPNext has no client ID to store.
Administrator consent and approval
Some tenants require a Global Administrator or Privileged Role Administrator to grant consent for mail permissions before users can authorize an application. Ask your identity team which approval path applies and who signs off on new application registrations. Start this request early, since it sits outside the ERPNext site and is often the longest wait in the process.
Site URL and HTTPS address
Record the exact public HTTPS address of the ERPNext site, including any subdomain and port. The Connected App generates a redirect URI from this address, and the Entra ID Web platform entry must match it character for character. A mismatch between an internal hostname and the public name is one of the most common causes of failed sign-in, so confirm which address users actually open.
System Manager access on the site
Confirm that the person making the change holds the System Manager role on the ERPNext site. The Connected App, the Email Account and the Social Login Key style settings are all configured from desk screens restricted to this role. Check the role before the change window, since a user without it will reach the Entra ID step and then be unable to finish the ERPNext side.
Confirm the ERPNext version
Before you configure anything, check the ERPNext and Frappe Framework version on your site against the supported versions page and confirm it is on a listed release. Steps and screen labels can differ between major versions, so follow the guide that matches your installed version. Record the version in your change ticket so that the test and rollback notes refer to the same release.
Configure the Connected App and Entra ID registration in order
This sequence links a Frappe Connected App to a Microsoft Entra ID app registration so ERPNext can request OAuth tokens for mail instead of stored passwords. It finishes with an Email Account that sends and receives mail, which confirms the chain works end to end.
Create the Connected App in the Frappe site
An administrator opens the Connected App list in the ERPNext site and creates a new record for Microsoft email. Fill in the provider fields as the Frappe Framework Microsoft email OAuth guide describes, leave the client ID empty for now, and save. Copy the redirect URI that the form displays, because the Entra ID registration needs it exactly as shown. Check: the Connected App is saved and the redirect URI is visible and copied to a secure note.
Register the application in Microsoft Entra ID
A Microsoft 365 administrator, or a user with permission to register applications, signs in to the Microsoft Entra admin center and creates a new app registration. Add the copied Connected App redirect URI and set its platform type to Web, since the Frappe guide specifies that platform. Confirm the redirect URI matches character for character, including the scheme and trailing path. Check: the app registration appears in the directory with the Web redirect URI listed under Authentication.
Grant the mail permissions the registration needs
In the app registration, review the API permissions that the Frappe guide and your mail design require for sending and reading mail, and confirm with your Microsoft 365 administrator whether tenant-wide consent is needed. Mail permissions can be broad, so ask your security team to approve the scopes before consent is granted. Check: the permissions list shows the scopes you agreed, and the administrator has granted consent where your tenant requires it.
Copy the application client ID into the Connected App
From the app registration overview page, copy the application (client) ID. Return to the Connected App in ERPNext, paste the value into the client ID field, and save. Keep the client secret or credential handling consistent with your secrets policy, and do not paste secrets into tickets or chat. Check: the Connected App saves without validation errors and the client ID shown matches the value in Entra ID.
Authorize the Connected App sign-in
From the Connected App, start the authorization flow so Microsoft prompts for sign-in and consent for the mailbox account that ERPNext will use. Sign in with that mailbox account and accept the requested permissions. Confirm the flow returns to the ERPNext site without an error page. Check: the sign-in prompt completes, the redirect returns to ERPNext, and the Connected App shows an authorized state or stored token.
Create the Email Account with OAuth selected
In ERPNext, create an Email Account for the mailbox and choose the OAuth option that references the Connected App rather than entering a password. Set the outgoing and incoming server details that match the Microsoft 365 mailbox and the default sender address. Save the record without enabling additional features until the basic path works. Check: the Email Account saves and the authorized Connected App appears as its authentication source.
Test sending and receiving mail
Send a test message from the Email Account to an external address you control, then reply to it from that external mailbox so ERPNext pulls the message in. Confirm the outgoing message arrives with the expected sender and that the reply appears as a Communication record in the site. Check the scheduler and email queue logs if either direction fails. Check: the test message is delivered, and the reply is received and linked in ERPNext.
Why the redirect URI must match exactly
The redirect URI generated by the Connected App in ERPNext must match the redirect entry under the Web platform of the app registration in Microsoft Entra ID character for character. Scheme, host, port if present, and path all count. A registration that says http where the site serves https, a trailing slash that one side includes and the other omits, or a hostname that differs by one subdomain will fail at sign-in, usually with a redirect error from Microsoft rather than a clear message from ERPNext. Do not rely on the value you expect. Copy the URI from the Connected App in your own site, paste it into Entra ID, and compare the two strings before you test.
The value depends on the address your users actually type into the browser. If the site moves to a new domain, is renamed, or changes its TLS certificate hostname, the generated redirect URI changes too, and the Entra ID registration must be updated with it. The same applies when a reverse proxy, load balancer or ingress terminates TLS in front of the bench or container. Check that the public scheme and host reach ERPNext correctly (forwarded headers and the site configuration both matter), because a site that builds its URL from an internal address will produce a redirect URI that no user ever reaches. Confirm the public hostname with your network or platform team rather than inferring it from the internal setup.
Plan a change step for any domain move, certificate change or proxy edit: update the Entra ID redirect entry, update the Connected App if its values changed, and test a fresh sign-in for both sending and receiving accounts. Keep a staging site or test tenant if you have one, so you can verify the exact string before production changes. Ask Microsoft-side administrators who can edit the app registration, since a registration owned by another team can block the change you need.
Which settings map to which system
This table traces each value you handle during setup to the system that issues it and the field or record that receives it. Read it top to bottom in the order you set things up, and confirm each label against the current Frappe documentation before you publish or hand off the configuration. The main takeaway is that the redirect URI flows from ERPNext to Entra ID, while the client ID flows back, so the two systems must be configured in that order.
| Value | Where it comes from | Where it goes |
|---|---|---|
| Redirect URI | Connected App in the ERPNext site | Web platform redirect URI in the Microsoft Entra ID app registration |
| Application (client) ID | Microsoft Entra ID app registration overview page | Client ID field in the Connected App in ERPNext |
| Client secret or credential | Entra ID app registration, as your organization's policy requires | Connected App in ERPNext, stored only in the site's secure fields (confirm the field name in the Frappe guide) |
| Mailbox address | The Microsoft 365 or Outlook mailbox you authorize | Email Account record in ERPNext, username and sender address fields |
| Outgoing mail settings | Microsoft 365 SMTP host, port and encryption settings for the mailbox | Outgoing mail configuration on the Email Account in ERPNext |
| Incoming mail settings | Microsoft 365 IMAP host, port and encryption settings for the mailbox | Incoming mail configuration on the Email Account in ERPNext |
| Consent and sign-in result | Microsoft sign-in and consent prompt during the first connection | OAuth token stored against the Connected App and used by the Email Account |
Securing the OAuth mail connection
An OAuth mail connection is only as safe as the people who can change it and the permissions the Microsoft app registration grants. The cards below cover who edits the Connected App and Email Account, which permissions to accept, how to avoid a shared mailbox login, how to manage any client secret or certificate, and how to keep a record of changes.
Limit who edits mail settings
The Connected App and the Email Account in ERPNext both control where outgoing mail is sent and which mailbox is used. Restrict edit rights on these DocTypes to a small administrator group through role permissions, and confirm that users who manage customers or sales documents cannot change them. Review that list whenever staff change roles, because a single broad role can expose mail configuration to people who do not need it.
Review requested Microsoft permissions
Before consenting, read the Microsoft permissions the app registration requests in Microsoft Entra ID and ask whether each one is needed for sending and receiving mail. Confirm with your Microsoft 365 administrator which permissions your tenant policy allows third-party apps to request, and whether admin consent is required. Record the approved list so a later change to the app registration is visible during review.
Avoid a shared mailbox login
Connecting ERPNext to one personal mailbox ties every system email to a single person's account, which breaks when that person leaves or changes password policy. Decide whether the connection should use a dedicated service mailbox or a shared address such as an accounts or support alias, and confirm with Microsoft 365 how that mailbox is licensed and whether it can sign in interactively. Keep the mailbox owner and the approver of the connection written down.
Manage the client secret lifecycle
If your chosen flow uses a client secret or certificate for the Entra ID app registration, it has an expiry date that someone must renew. Record the expiry, set a reminder well before it, and store the value in your secrets manager rather than in a spreadsheet or ticket. Confirm the exact credential type the Frappe guide asks for, because a silent expiry stops all ERPNext mail delivery and can look like a generic SMTP failure.
Rotate and revoke access on exit
When the administrator or owner who set up the connection leaves, the access they granted should be reviewed. Plan how to revoke consent or remove the app registration, how to disable the Email Account, and who can re-authorize it. Test this path once in a non-production site so the steps are known before they are needed under pressure.
Log changes to mail settings
Mail configuration changes should leave a trail that an auditor or security engineer can read. Review the Version history that ERPNext keeps for changed documents, and forward Microsoft Entra ID sign-in and consent logs to your central logging platform. Confirm the retention period your organization requires, since the logs you need may sit in Microsoft tenant settings rather than in ERPNext.
Why the Microsoft sign-in or mail test fails
This table lists the failures most often seen when connecting ERPNext to Microsoft 365 with OAuth, with the likely cause, the check to run and the fix for each. Work through the rows in order, because a tenant-side block can look like a redirect URI problem. Confirm each Microsoft setting against your own tenant, since admin roles and policy names vary by organization.
| Failure | Likely cause | Check and fix |
|---|---|---|
| Redirect URI mismatch | The Web redirect URI in the Entra ID app registration does not match the callback URL shown in the ERPNext Connected App, often because the site URL, protocol or path differs. | Copy the redirect URI from the Connected App exactly, including https and any trailing path, into the app registration's Web platform, then retry sign-in. |
| Wrong application (client) ID | The client ID copied into the Connected App belongs to a different app registration, a test app or an earlier attempt. | Compare the Application (client) ID on the Entra ID overview page with the value saved in the Connected App and correct it. |
| Missing admin consent | The requested Microsoft Graph or mail permissions were never granted by a tenant administrator, so Microsoft blocks the token request. | In Entra ID, open API permissions for the app and grant admin consent. Confirm with the tenant administrator that the consent applies to the tenant in use. |
| Mailbox without Exchange Online access | The signing-in account has no Exchange Online mailbox or licence, or the mail flow is hosted elsewhere, so mail actions fail after sign-in succeeds. | Confirm the account has an active mailbox in Exchange admin center and that its licence includes Exchange Online. Test by sending a message from that mailbox in Outlook on the web. |
| Tenant policy blocking the app | A conditional access policy, user consent restriction or app governance rule stops the app or the sign-in location, so the login is refused before mail is reached. | Review sign-in logs in Entra ID for the failed attempt and the policy named there. Ask the administrator to allow the app or adjust the policy scope for the service account. |
| Mail not arriving because the outgoing account is disabled | The Email Account record in ERPNext is disabled, the default outgoing account is not set, or the scheduler and email queue are not running, so messages are held or never sent. | Open the Email Account in ERPNext, confirm it is enabled and set as the default outgoing account, then check the Email Queue for errors and confirm background jobs are processing. |
Questions buyers ask about Microsoft 365 email for ERPNext
Can our own team set up ERPNext email with Microsoft 365 using OAuth?
Yes, if someone on your team has administrator rights in Microsoft Entra ID and can create an app registration, and someone can administer the ERPNext site. The core steps are documented by Frappe: create a Connected App in the ERPNext site, register an app in Microsoft Entra ID with the Connected App's redirect URI added as a Web platform, then copy the application (client) ID back into the Connected App. The steps are short, but the surrounding decisions take longer: which mailboxes send and receive, how Exchange Online mail flow and sending policies are set, and how the change is tested. Teams that already run Microsoft 365 administration and ERPNext operations usually handle this in-house. Teams without a Microsoft 365 administrator often need one involved from the start.
How long does it take and what drives the effort?
The effort depends mainly on tenant admin access, the number of mailboxes and the policy reviews your organization requires. Ask for the work to be broken into these parts in any quote: confirming who can grant admin consent in your Microsoft 365 tenant, mapping which ERPNext users and shared mailboxes need outbound and inbound email, testing sends and receives with real documents such as invoices and reminders, and recording the configuration for your change process. Each mailbox that needs a separate setup or a delegated rule adds work. Any policy review by your security or compliance team adds calendar time that no vendor can shorten. We do not publish a price list, so ask for a fixed-scope quote with the parts and deliverables listed.
What do we need to provide from our IT team?
Your IT team typically provides four things: an account with rights to register applications in Microsoft Entra ID, a decision on who can grant admin consent, the list of mailboxes and their purpose, and access to the ERPNext site with a user who can manage settings. Your team should also confirm the redirect URI generated by ERPNext before it is entered into the app registration, so the value matches the site address exactly. Ask your Microsoft 365 administrator to confirm that outbound mail is allowed for the chosen mailboxes under your current policies. Plan a change window and a test mailbox so that live customer correspondence is not the first thing tested.
Does self-hosting ERPNext change the Microsoft 365 steps?
The Microsoft side stays the same, but the redirect URI depends on the address of your ERPNext site, so it changes whenever the public hostname, TLS setup or reverse proxy changes. On a self-hosted deployment, whether built with bench, Docker Compose or another method, the Connected App must match the URL users actually visit. If you run several sites or move from a test hostname to production, each site needs its own correct redirect URI. Check that the site is reachable over HTTPS at the address you register, and that the outbound network path from the ERPNext server to Microsoft sign-in endpoints is allowed by your firewall or proxy. Frappe Cloud hosting and self-hosting follow the same OAuth logic, but your team owns the network checks when you self-host.
Is OAuth more secure than storing a mailbox password in ERPNext?
OAuth avoids storing a user's Microsoft 365 password in ERPNext, and access is granted through Microsoft's consent and sign-in process. That reduces the exposure of a long-lived password, but it does not remove the need for control. Your security team should decide which account authorizes the connection, how consent is reviewed, and how access is revoked when a person leaves. Record the app registration owner, its client secret handling if one is used, and the administrative roles that can change it. Ask your security reviewer to check the configuration against your own access policies rather than assuming it is compliant.
What should we check after go-live?
After go-live, test outbound documents such as sales invoices and payment reminders, confirm inbound replies are linked to the correct documents, and check that the connection still works after a password change or a policy update in Microsoft 365. Review the ERPNext email queue and error logs for failed sends, and confirm that scheduled jobs running in the background are processing email. Keep a written record of the app registration, redirect URI, mailboxes and owners, so an upgrade or hostname change does not break sending. If you want continued checks through upgrades, ask about support or retainer options in your quote.
Will this work with Outlook.com or other email providers?
This guide covers Microsoft 365 and Outlook accounts that sit in a Microsoft Entra ID tenant. Personal Outlook.com accounts and other email providers follow different authentication rules, so do not assume the same app registration applies to them. Confirm the account type and tenant with your Microsoft 365 administrator before planning the work. For a mailbox outside Microsoft 365, ask for a separate assessment that names the provider and the sign-in method it supports.
Keeping ERPNext email working after go-live
Email through Microsoft 365 fails quietly more often than it fails loudly, so the first job after go-live is to make failures visible. Use the email queue and the Email Account settings in ERPNext to watch outgoing messages that stay queued or end in an error, and check incoming mail sync for the connected mailbox on a fixed schedule. Pair those checks with the delivery and scheduler checks described in ERPNext operations and performance, because a stalled background worker or scheduler looks the same to users as a broken mailbox. Record a baseline of normal queue behavior in the first weeks so that a change is easy to spot. Confirm with your own administrator which alerts, if any, your organization already routes from the ERPNext logs and where those messages would land.
Review the integration after any change to the Microsoft side. Password resets, conditional access changes, app consent updates, and changes to the client secret or certificate in Microsoft Entra ID can all break the OAuth exchange that the Email Account depends on, and the error may appear only when a token refresh is next attempted. Keep a short runbook that names the app registration owner, the Connected App on the site, and the mailbox the Email Account uses, so that whoever receives a failure knows where to look first. Confirm with your Microsoft 365 administrator how and when the client credentials expire, since that date should appear on your operations calendar rather than be discovered during an outage.
Upgrades of ERPNext or Frappe can change how Email Accounts and OAuth settings behave, so test email after every upgrade in a staging site before production. Check the release notes for the version you are moving to, and confirm that the Connected App, the redirect URI and the Email Account still match the site's URL. Revisit the Connected App when the site domain or hostname changes, when you move between environments, when you add a second mailbox, or when Microsoft announces a change to the sign-in flow that your tenant has not yet tested. Treat that review as part of the change plan for any upgrade, and ask any partner you use to include it in the written scope.
How DeployOpen works on this
DeployOpen plans and implements ERPNext email with Microsoft 365 using OAuth inside your own infrastructure, starting from a written scope that names the mailboxes, sending and receiving paths, and Microsoft tenant involved. We configure the Connected App, the Microsoft Entra ID registration and the redirect URI on your site, then test and document each step for your administrators.
How we scope
- Confirm which ERPNext sites and Email Accounts will send and receive mail through Microsoft 365
- Agree which Microsoft 365 or Outlook tenant, mailboxes and shared addresses are in scope
- Record who holds Entra ID administrator rights and who approves the app registration
- Fix the written scope, deliverables and timeline before any configuration begins
How we build
- Create the Connected App on your ERPNext site with the agreed scopes and callback settings
- Register the application in Microsoft Entra ID with the Connected App redirect URI as a Web platform
- Copy the application (client) ID back into the Connected App and complete the OAuth authorization
- Test outbound sending and inbound receiving with the mailboxes and aliases you actually use
How we hand over
- Document each Entra ID setting, redirect URI and Connected App field with its owner and purpose
- Provide a runbook for rotating secrets, adding mailboxes and reauthorizing after credential changes
- Walk your administrators through a test send, a test receive and the failure checks they should repeat
- Record configuration changes so that future audits can trace who approved each setting
How we support
- Engagements are fixed-scope, and ongoing support, upgrades and testing are available as a retainer
- Review the OAuth setup again when ERPNext or Frappe versions in your support plan change
- Confirm with your Microsoft 365 administrators how tenant policy changes affect the app registration
- Agree in writing which support tasks, response expectations and fees apply after go-live
