ews-javascript-api is a JavaScript/TypeScript library that provides an API for interacting with Microsoft Exchange Web Services (EWS), aiming to be a counterpart to the C# EWS Managed API. It supports Office 365 OAuth, enabling interaction with modern Exchange Online environments. The current stable version is 0.15.3, with recent releases focusing on bug fixes, security dependency updates, and improved OAuth support. While development has had periods of activity and dormancy, the project is actively maintained to address issues and enhance features like async/await integration and a modular `@ewsjs` namespace. Key differentiators include comprehensive TypeScript type definitions, support for both Node.js and browser environments (via `ews-js-api-browser`), and built-in OAuth support for Exchange Online/Office 365 through `EwsOAuthHelper`, making it suitable for modern web and server-side applications needing to access Exchange data programmatically.
npm install ews-javascript-apiVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to initialize the ExchangeService with Office 365 OAuth credentials using the `EwsOAuthHelper` to obtain an application-only access token, preparing it for subsequent EWS operations. It sets up environment variables for sensitive credentials and includes basic error handling, illustrating the modern authentication flow.
Upgrade your Node.js runtime environment to version 12 or newer. Use `nvm` or your package manager to manage Node.js versions.
Ensure your import statement for `EwsOAuthHelper` is `import { EwsOAuthHelper } from 'ews-javascript-api/lib/EwsOAuthHelper';`.Store the token's `expiresIn` value and re-call `oAuthHelper.getAppAccessToken()` proactively before the current token expires. Consider wrapping EWS operations in a function that ensures a valid token is always present.
Always use `import` statements for `ews-javascript-api` classes and functions. Ensure your project is configured for ESM, particularly in `package.json` with `"type": "module"` or when transpiling TypeScript.
Verify that `ExchangeService` and other classes are correctly imported using `import { ClassName } from 'ews-javascript-api';` and that the instance is created before use, e.g., `const ews = new ExchangeService(ExchangeVersion.Exchange2016);`.For development/testing (use with caution in production due to security implications), set `process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0';` before making EWS calls. For production, properly configure Node.js to trust your CA certificate (e.g., via `NODE_EXTRA_CA_CERTS` environment variable).
Implement token refresh logic. Before making EWS calls, check the token's validity and, if expired or close to expiration, call `oAuthHelper.getAppAccessToken()` again to retrieve a fresh token and update `ews.Credentials`.
Ensure the path is correct and case-sensitive. The `lib/` directory is critical for some sub-modules. Verify your `tsconfig.json` `moduleResolution` and `baseUrl` if you are having issues with non-relative imports. For `EwsOAuthHelper`, the correct import is `import { EwsOAuthHelper } from 'ews-javascript-api/lib/EwsOAuthHelper';`.