Registry / communication / ews-javascript-api

ews-javascript-api

JSON →
library0.15.3jsnpmunverified

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-api
INSTALL
IMPORT
SIG · EWS-JAVASCRIPT-API
E
ews-javascript-api
communicationjavascriptv0.15.3
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

ExchangeService
import { ExchangeService } from 'ews-javascript-api';
const ExchangeService = require('ews-javascript-api').ExchangeService;
Main class for EWS operations. CommonJS `require` is generally discouraged since modern Node versions and TypeScript projects primarily use ESM.
EwsOAuthHelper
import { EwsOAuthHelper } from 'ews-javascript-api/lib/EwsOAuthHelper';
import { EwsOAuthHelper } from 'ews-javascript-api';
This helper class for OAuth is located in a subpath, not directly on the main package export. Importing from the root will result in undefined.
ExchangeVersion
import { ExchangeVersion } from 'ews-javascript-api';
const ExchangeVersion = require('ews-javascript-api/lib/Enumerations/ExchangeVersion');
An enumeration used to specify the target Exchange server version for operations. Direct import from the root is preferred over deep imports.

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.

import { ExchangeService, OAuthCredentials, ExchangeVersion } from "ews-javascript-api"; import { EwsOAuthHelper } from "ews-javascript-api/lib/EwsOAuthHelper"; const clientId = process.env.EWS_CLIENT_ID ?? ''; const clientSecret = process.env.EWS_CLIENT_SECRET ?? ''; const tenantId = process.env.EWS_TENANT_ID ?? ''; const exchangeUrl = process.env.EWS_URL ?? 'https://outlook.office365.com/EWS/Exchange.asmx'; async function main() { if (!clientId || !clientSecret || !tenantId) { console.error('Missing EWS_CLIENT_ID, EWS_CLIENT_SECRET, or EWS_TENANT_ID environment variables.'); return; } try { const oAuthHelper = new EwsOAuthHelper({ clientId, clientSecret, tenantId }); console.log('Attempting to get application access token...'); const token = await oAuthHelper.getAppAccessToken(); console.log('Successfully obtained access token. Expires in:', token.expiresIn); const ews = new ExchangeService(ExchangeVersion.Exchange2016); ews.Url = exchangeUrl; // Set your EWS endpoint URL ews.Credentials = new OAuthCredentials(token.accessToken); // Example: Find the Inbox folder // You might need to refresh the token if it expires during long-running operations. // A typical pattern is to wrap EWS calls in a function that checks token validity. // const wellKnownFolderName = new WellKnownFolderName(WellKnownFolderName.Inbox); // const findFoldersResults = await ews.FindFolders(wellKnownFolderName, new FolderView(10)); // console.log('Found Inbox folder:', findFoldersResults.Folders[0].DisplayName); console.log('ExchangeService initialized with OAuth credentials. Ready for EWS operations.'); // Placeholder for actual EWS operations, e.g., finding items or sending emails. // await ews.FindItems(WellKnownFolderName.Inbox, new ItemView(10)); } catch (error) { console.error('Error during EWS operation:', error); if (error instanceof Error) { console.error('Error message:', error.message); } } } main().catch(console.error);
Debug
Known issues
breakingVersion 0.11.0 and later require Node.js version 10 or higher, with version 12 being preferred. Earlier Node.js versions are not supported and will likely lead to runtime errors due to updated dependencies and language features.
fix
Upgrade your Node.js runtime environment to version 12 or newer. Use `nvm` or your package manager to manage Node.js versions.
affects: >=0.11.0
gotchaThe `EwsOAuthHelper` class, which is crucial for modern Office 365 authentication, must be imported from its specific subpath `ews-javascript-api/lib/EwsOAuthHelper`. A direct import from the root package `ews-javascript-api` will fail to find the class, leading to runtime errors.
fix
Ensure your import statement for `EwsOAuthHelper` is `import { EwsOAuthHelper } from 'ews-javascript-api/lib/EwsOAuthHelper';`.
affects: >=0.15.0
gotchaWhen using OAuth, access tokens have a limited lifespan. You must implement logic to periodically refresh the access token using `oAuthHelper.getAppAccessToken()` before it expires, especially for long-running processes or frequent EWS calls. Failure to do so will result in authentication failures (401 Unauthorized errors).
fix
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.
affects: >=0.15.0
gotchaThe library primarily uses ESM (ECMAScript Modules) syntax for imports and is designed for modern JavaScript environments. While some CommonJS `require()` might work for basic usage, mixing module systems or using outdated `require()` patterns can lead to unexpected behavior or build issues, especially with TypeScript projects.
fix
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.
affects: >=0.11.0
Errors
Common errors & fixes
TypeError: Cannot read properties of undefined (reading 'apply') or Cannot set properties of undefined (setting 'Credentials')
This usually indicates that the `ExchangeService` instance was not properly initialized, or a method was called on an undefined object, often due to an incorrect import or a `this` context issue.
fix
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);`.
Error: unable to get local issuer certificate (in Node.js)
This error typically occurs when Node.js cannot verify the SSL certificate of the EWS endpoint, often in corporate environments with custom proxy certificates or self-signed certificates.
fix
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).
401 Unauthorized: Access token is expired or invalid
The OAuth access token provided in `OAuthCredentials` has expired or is malformed/invalid, leading to authentication failure with the Exchange server.
fix
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`.
Error: Cannot find module 'ews-javascript-api/lib/EwsOAuthHelper' or similar path errors
The module resolver cannot locate the specified path for `EwsOAuthHelper` or other sub-modules.
fix
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';`.
Upgrade
Version history
0.15.3latest on npm
Audit
Dependencies
@ewsjs/xhrrequiredInternal dependency for handling HTTP requests, explicitly mentioned as updated to 3.1.0 in v0.15.0.
Agent activity
32 hits · last 30 days
node
26
Amazon
1
OpenAI (training)
1
Resources
ews-javascript-api — npm install ews-javascript-api · libregistry