Learn how to use the EWS API to authenticate accounts into your app and discover how Nylas makes it easy to integrate full email, calendar, and contacts functionality.
Microsoft’s Exchange Web Services(EWS) API provides users with an intuitive interface that allows developers to add full Exchange data and functionality into their app. With direct SOAP implementation, clients can send and receive web service messages from client applications, portal applications, and service applications, an access nearly all the information stored in an Exchange Online, Exchange Online as part of Office 365, or an Exchange server mailbox by simply using the EWS Managed API.
This article will cover the major components of the EWS API and explain just what it takes to build a full integration with EWS accounts. It will also demonstrate how the Nylas Communications Platform abstracts away much of the complexity of building a direct integration with the Microsoft EWS API, enabling you to build your email, calendar and contacts integration seamlessly and efficiently.
Download and run Exchange Server – This is for building integrations with on-prem Exchange servers.
Once that is established, you are ready to authenticate your development environment, utilizing standard web authentication protocols to help secure the communication between your application and the Exchange server. For those users that are targeting Exchange Online, the authentication method that you choose must use HTTPS to encrypt the requests and responses that your application sends. We recommend that you use HTTPS for any request that your application sends to an EWS endpoint to help secure communication between your application and an Exchange server.
Exchange provides two authentication options: OAuth 2.0 for Exchange Online, and NTLM for on-premises installations of Exchange. Let’s take a look at how to use these authentication mechanisms.
OAuth Authentication
OAuth is the gold standard for app to app authentication, and it should be used whenever possible. We recommend all applications use OAuth to connect to all Exchange Online services. The advantage in security over basic authentication is worth the additional work required to implement OAuth in your application. With that important point out of the way, there are also some disadvantages that you should be aware of.
Advantages
OAuth is an industry-standard authentication protocol.
Authentication is managed by the third-party provider. Your application doesn’t need to collect and store the Exchange credentials.
Your app only receives an opaque token from the authentication provider, so a security breach in your application can only expose the token, not the user’s Exchange credentials. This means better security for you with less worry about protecting sensitive data.
Disadvantages
OAuth relies on the EWS authentication service. This can impose additional costs on your organization or your customers.
The OAuth standard is more difficult to implement than basic authentication because you need to integrate your application with both the authentication provider and the Exchange server.
In order to minimize these disadvantages, we recommend using the Microsoft Azure Active Directory Authentication Library(ADAL) to authenticate users to Active Directory Domain Services(AD DS) in the cloud or on-premises and then obtain access tokens for securing calls to an Exchange server. Exchange Online requires tokens issued by the Azure Active Directory service, which is supported by the ADAL. But you can use any third-party library for this action.
Microsoft offers two types of OAuth permissions to access EWS APIs in Exchange Online, delegated permissions and application permissions. Before you proceed with the tutorial, you will need to choose the specific permission type you wish to use:
Delegated permissions are used by apps that have a signed-in user present. For these apps, either the user or an administrator consents to the permissions that the app requests and the app can act as the signed-in user when making API calls.
Application permissions are used by apps that run without a signed-in user present; for example, apps that run as background services or daemons and can access multiple mailboxes.
To use EWS OAuth, you first need to register your application, and get an application ID issued by Azure Active Directory. The EWS docs contain a bunch of code examples that demonstrate how to get access tokens for delegated and application permissions.
NTLM Authentication
NTLM authentication is only available for on-premises servers. For applications that run inside of a corporate firewall, integration between NTLM authentication and the .NET Framework provides a built-in means to authenticate your application:
Advantages
Works“out of the box” with your Exchange server. You can configure access to Exchange services by using an Exchange Management Shell cmdlet.
Uses the .NET Framework CredentialCache object to automatically get user’s credentials.
Disadvantages
Users must be logged on to a domain to use NTLM authentication.
It can be difficult to access email accounts that are not associated with the user’s domain account.
Service applications must have a domain account to take advantage of NTLM authentication.
Take a look at the NTLM Authentication code examples in the docs to learn more about how to use this feature.
Nylas Makes Exchange Integrations Easy and Maintenance-Free
The Nylas Communications Platform integrates with 100% of email, calendar, and contacts providers, including Exchange, Office365, and Outlook. With Nylas, you can build a full email, calendar, and contacts integration in a fraction of the time it would take to build a direct integration with Exchange. Let’s take a look at the features Nylas offers to make it dead simple to build your first email, calendar, and contacts integration.
Nylas Hosted Auth
Nylas Hosted Auth is the quickest and easiest way to setup user authentication for your app. Simply redirect users to a Nylas login page and we’ll handle the rest including auto-detection of third party providers and managing token exchanges with providers like Microsoft.
The Nylas Hosted Auth process is very similar to authentication with the the EWS OAuth authentication, but with some added magic to make your life much easier.
Nylas auto-detects the email account provider, and initializes the appropriate authentication process with the third-party API. In the case of Exchange accounts, Nylas initializes the EWS OAuth consent process.
After the user logs in to their account, Nylas redirects them back to your app, and returns the appropriate OAuth credentials. If you’re building a server-side app, Nylas returns an authorization code that can be exchanged for a user access token. If you’re app is client-side, Nylas returns the access token directly.
Your app uses the access token to make requests to the Nylas Email, Calendar, and Contacts APIs on behalf of the users.
Then, you can make a request to the Account endpoint to return information about the connected user account.
There are two key components of Nylas Hosted Auth that makes development easier:
Nylas auto-detects 100% of email, calendar, and contacts providers, even for Exchange organizations that use their own company domain for their email accounts. Additionally, you can connect user accounts for any other third party email, calendar, and contacts provider with no additional development work.
Nylas handles negotiating with third party providers to manage OAuth credentials to ensure user accounts are always connected and synced.
Not to mention, the Nylas offers a modern REST interface that returns standard JSON, which is much easier to work with than the dated SOAP/XML interface Exchange provides. Nylas also provides SDKs for Python, Java, Node.js, and Ruby, to make getting started dead simple, where EWS is limited to .NET environments.
Focus on The Features Your Users Love
Ultimately, Nylas allows you to more quickly build your email, calendar, and contacts integration so you can spend more time building the features your users love. There’s no need to become an expert at Exchange integrations when you build with Nylas.
The Nylas Email API
The Nylas Email API provides full access to your Exchange email inboxes to ingest email data, manage and download email attachments, create drafts and send emails, and search email inboxes for specific content.
Here’s an example that requests the latest email message from a user’s inbox:
$ curl -X GET 'https://api.nylas.com/messages?limit=1' -H 'Authorization: Bearer ACCESS_TOKEN'
[
{
"subject": "Got some torpedos you need to stop?",
"body": "Have you heard about our new torpedo-jamming technology? ",
"from": [
{
"email": "Lamarr@player.com",
"name": "Hedy Lamarr"
}
],
"to": [
{
"email": "james****@yahoo.com",
"name": ""
}
],
"date": 1557950729,
"folder": {
"display_name": "Inbox",
"id": "7hcg****",
"name": "inbox"
},
"unread": true,
"starred": false,
...
}
]
Calendar management
Embedded contextual email
Scheduling automation
Automated outreach
Telehealth
Marketplaces
Recruiting
Document management
Real estate
Communications software
Docs
SDKs
Tutorials
API status
Changelog
Support
Blog
Events
Guides
Newsroom
Partners
Build vs. buy
Customer stories
Trust & security
Why Nylas
