How to connect Exchange (EWS) accounts

Connecting an on-premises Microsoft Exchange account works differently from connecting a cloud mailbox. Self-hosted Exchange servers speak Exchange Web Services (EWS), a SOAP protocol that predates the OAuth-based Microsoft Graph API used for Exchange Online and Microsoft 365. This recipe walks through the connect and grant flow for EWS so you can authenticate users on servers your customers run themselves.

For the complete server-side setup, including minimum versions and network configuration, read the Exchange on-premises provider guide. This page focuses on getting a grant once the server is ready. To read mail after connecting, see List Exchange messages.

How do I connect an Exchange EWS account to Nylas?

Create an EWS connector with the provider set to ews, add the scopes you need, then send the user through Nylas Hosted authentication with the same ews provider value. The user signs in with their Exchange credentials, and the API returns a grant ID you use for every API call afterward. The whole connect flow usually finishes in under 60 seconds when autodiscovery succeeds.

When should I use EWS instead of Microsoft Graph?

The deployment decides this for you. If the mailbox is hosted by Microsoft in the cloud, including Exchange Online, Microsoft 365, Office 365, and Outlook.com, use the microsoft connector built on Microsoft Graph and OAuth. If the organization runs its own Exchange server in its own data center, use the ews connector instead. There is no overlap: a single mailbox lives in exactly one of these two worlds.

Nylas keeps these separate because Exchange on-prem requires direct network requests to a specific server address and port, while Graph uses a managed cloud endpoint. To use the EWS connector, the server must run Exchange 2007 or later, and Exchange 2010 or later if you want starred messages. Microsoft announced EWS retirement in 2022 and recommends Graph, but many enterprises still run on-prem Exchange where EWS remains the only path. After you connect, the same Messages and Calendar APIs work across both provider types.

What authentication options does EWS support?

EWS authentication centers on a username and password rather than a redirect-based OAuth consent screen. During Hosted auth, the user enters an Exchange username, formatted as either [email protected] or DOMAIN\username, which usually matches their Windows login. Nylas authenticates against the server using the protocols the server accepts, commonly basic or NTLM authentication over a TLS connection, a handshake that usually finishes in under 5 seconds.

You have two ways to reach mailboxes. The simplest is per-user credentials, where each person enters their own password. The other is a service account with impersonation rights, which lets one privileged account act on behalf of many users without storing each user’s password. Impersonation is an Exchange server configuration your administrator enables, not a Nylas setting. One detail to plan for: accounts that have two-factor authentication turned on cannot use a normal password, so the user must generate an app password first. App passwords are 16 characters long and bypass the second factor for this single connection.

How do I create an EWS connector?

A connector tells the API which provider and scopes your application uses. Create the EWS connector once per application by sending a POST request to the /v3/connectors endpoint with the provider field set to ews. You can also add it from the Nylas Dashboard under the Connectors page by selecting the EWS item.

EWS defines three Nylas scopes: ews.messages for the Email API, ews.calendar for the Calendar API, and ews.contacts for the Contacts API. The connector’s scopes field takes a single value, so set it to the data type you need and create a separate connector for each additional data type. The request below creates a connector for mail and returns in under 2 seconds. For the full scope list and the dashboard steps, see the Exchange on-premises guide. Replace the bearer token with your API key before running it.

curl --request POST \
  --url "https://api.us.nylas.com/v3/connectors" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "provider": "ews",
    "scopes": "ews.messages",
    "settings": {}
  }'

How do I connect a user and get a grant?

With the connector in place, send the user through Nylas Hosted authentication. A grant represents one connected Exchange mailbox, and you create it in three steps. First, redirect the user to the Hosted auth page with a GET /v3/connect/auth request, passing provider=ews. Second, the user signs in with their Exchange account and, if autodiscovery fails, enters the server address such as mail.example.com under additional settings. Third, exchange the returned code for a token to receive the grant ID.

The redirect URL looks like the example below. Set redirect_uri to a callback you registered, then handle the returned code on that route. The whole flow usually completes in under 60 seconds when autodiscovery succeeds.

curl --request GET \
  --url "https://api.us.nylas.com/v3/connect/auth?client_id=<NYLAS_CLIENT_ID>&provider=ews&redirect_uri=<YOUR_CALLBACK_URL>&response_type=code"

Store the grant ID securely once you have it. Every subsequent request, whether listing messages or reading calendar events, uses that grant ID as the account identifier. For the broader concept of grants and tokens, see the authentication overview.

Things to know about Exchange (EWS)

Exchange on-prem has behaviors that do not appear with cloud providers, and most connection problems trace back to one of these. Plan for them before you ship.

Autodiscovery and the server address

Nylas runs Exchange autodiscovery by default to find the correct EWS endpoint from the user’s email address. When autodiscovery is misconfigured, which happens often in enterprise environments, the user must enter the server address manually during sign-in. If issues persist, the domain administrator can validate settings with Microsoft’s Remote Connectivity Analyzer at testconnectivity.microsoft.com. Microsoft documents the lookup sequence in its autodiscover for Exchange reference. Autodiscovery typically checks several candidate URLs, so a single DNS or certificate mistake can stall the entire connection.

Impersonation and service accounts

If you use a service account, the Exchange administrator must grant it the ApplicationImpersonation role through a management role assignment. With that role, one account can connect mailboxes across the organization without each user entering a password. This is the standard pattern for connecting hundreds of mailboxes at once. Without the role, impersonated requests fail with an access-denied response even when the password is correct, so confirm the assignment before debugging credentials.

Throttling policies

Exchange rate limits are set by the server administrator through a throttling policy, not by Nylas, so the exact ceilings vary per deployment. When the server throttles a request, the API surfaces a Retry-After header telling you how long to wait, often 30 seconds or more, before retrying. For apps that sync frequently, lean on webhooks rather than polling so you stay well under whatever limit the administrator configured. A single aggressive sync loop can trip a tight throttling policy in seconds.

TLS and network reachability

The server must accept connections from outside the corporate network with a valid TLS certificate. The connection uses port 443 by default, so a mailbox locked behind a VPN or an internal-only firewall rule cannot be reached. If the server sits behind a firewall, allowlist Nylas IP addresses, available on contract plans with static IP routing. Self-signed or expired certificates also break the connection, so verify the certificate chain is trusted publicly.

Message ID format

EWS message IDs are not stable. When a message moves between folders, its Nylas message ID changes, because Exchange reassigns the identifier on every folder move. Treat message IDs as folder-specific pointers and use the InternetMessageId header for tracking a message across moves. One caveat: copies of the same message in different folders can share one InternetMessageId, so it correlates messages but is not a unique key.

What’s next

• Exchange on-premises provider guide for full server setup, minimum versions, and network requirements
• List Exchange messages to read mail once the grant is connected
• Authentication overview for grants, tokens, and the Hosted auth flow
• Create a connector for the full connector API reference
• Webhooks to receive real-time updates instead of polling