Version:
Only show these results:

Authenticate Exchange on-prem servers with Nylas

You can use the Nylas v3 EWS connector to connect to email accounts hosted on Exchange on-prem servers. This allows you to use the Nylas Email, Calendar, and Contacts APIs.

⚠️ Microsoft announced the retirement of Exchange Web Services in 2022 and strongly recommended that all users migrate to use Microsoft Graph. Users on Exchange Online have already been migrated.

How is EWS different from the Microsoft connector?

Microsoft Exchange on-prem is a self-hosted application that an administrator can run on their own servers to provide email, calendar, and contacts directory features to their organization. This model predates modern cloud architecture, and requires anyone who wants to connect to this service (including Nylas) to make network requests directly to the specified server using the server address and port. While Microsoft has built some features such as autodiscovery to smooth this process, they are sometimes misconfigured, or not configured.

Microsoft announced the EWS retirement and is deprecating some of the services that supported it. However, Exchange is still installed on many private servers and used by many people.

Nylas v3 uses a separate connector to handle Exchange on-prem authentication requests because although it is technically a Microsoft product, it uses a totally different connection process.

If your project only uses the Email APIs, you can use an IMAP connector for these accounts instead.

Exchange on-prem minimum version

To use the Exchange on-prem connector with Nylas, the Exchange server must be running Exchange 2007 or later.

If you want to use starred messages, the server must be running Exchange 2010 or later.

Add an EWS connector

You can add an EWS connector to your application by making a POST /v3/connectors request, specifying the provider as ews, and including scopes that indicate which API services you want to use.

To add the EWS connector from the Dashboard:

  1. In the v3 Dashboard, navigate to the application you want to use EWS with.
  2. Click Connectors in the left navigation.
  3. Find the EWS item, and click the plus icon (+).
  4. Click the EWS connector and select the scopes you want to use.

You must set Nylas-defined scopes on the EWS connector to indicate which API objects you want to use. Add one or more of the following scopes to enable EWS access.

  • ews.messages
  • ews.calendars
  • ews.contacts

Connect an end user with EWS and Hosted authentication

  1. Send the end user to the Nylas Hosted auth login page by making a GET /oauth/authorize request and specifying the provider as ews.
  2. Have the end user log in using their Exchange account name and password, and if necessary, the server-specific details.
  3. Complete the auth flow by exchanging a token with the provider. The API response contains the grant ID for the end user, which you can use query for their data.

Using autodiscovery with Exchange

In most scenarios, end users can log in to Microsoft Exchange using their email address and password. This is because Nylas performs autodiscovery by default to determine the best server settings for the login attempt.

However, autodiscovery is sometimes unable to determine the correct settings. When this happens, the end user can enter more settings in the Advanced section of the login screen. If issues persist, the domain administrator can test the Exchange server's autodiscovery settings.

Log in using advanced settings

If autodiscovery is unavailable when an end user authenticates using Hosted auth, the end user must click Additional settings and enter information about the Exchange servers.

  1. Enter the Exchange username, formatted as either username@example.com or DOMAIN\username. This is usually the same as the end user's Windows login.
  2. Enter the Exchange server address (for example, mail.example.com). This address is usually visible in the Address bar when the end user logs in to the Outlook Web App.

    🔍 The end user might need to contact their Exchange or IT administrator to get the correct the connection settings.

The Microsoft Exchange login page showing the "Advanced Settings" options.

EWS limitations

Nylas v3 currently supports self-hosted EWS instances using the ews provider and Hosted authentication.

App password required for Two-factor authentication

If an end user has two-factor authentication (2FA) enabled for their account, they must generate an app password.

Exchange with private networks and VPNs

For an end user to connect, the Exchange server must not be in a private network or require a VPN to access it.