Exchange Web Services JavaScript API

Common errors

• TypeError: Cannot read properties of undefined (reading 'apply') or Cannot set properties of undefined (setting 'Credentials')

  cause 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)

  cause 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

  cause 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

  cause 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';`.

Warnings

• breaking Version 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.
• gotcha The `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';`.
• gotcha When 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.
• gotcha The 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.

Install

• npm install ews-javascript-api npm
• yarn add ews-javascript-api yarn
• pnpm add ews-javascript-api pnpm

Imports

• ExchangeService
  wrong:

  const ExchangeService = require('ews-javascript-api').ExchangeService;

  correct:

  import { ExchangeService } from 'ews-javascript-api';

  Main class for EWS operations. CommonJS `require` is generally discouraged since modern Node versions and TypeScript projects primarily use ESM.
• EwsOAuthHelper
  wrong:

  import { EwsOAuthHelper } from 'ews-javascript-api';

  correct:

  import { EwsOAuthHelper } from 'ews-javascript-api/lib/EwsOAuthHelper';

  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
  wrong:

  const ExchangeVersion = require('ews-javascript-api/lib/Enumerations/ExchangeVersion');

  correct:

  import { ExchangeVersion } from 'ews-javascript-api';

  An enumeration used to specify the target Exchange server version for operations. Direct import from the root is preferred over deep imports.

Quickstart

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);