EWS API for TypeScript/JavaScript - ported from OfficeDev/ews-managed-api - node, cordova, meteor, Ionic, Electron, Outlook Add-Ins
MIT License
Contact @gautamsi for support. Use for 1:1 support and paid support. Also looking for sponsors to fund remaining development on this.
===========================================================================================
see demo repo https://github.com/ewsjs/oauth-demo which has working example - https://github.com/ewsjs/oauth-demo/blob/main/examples/msal-node-samples/auth-code/index.js to find out how to use oAuth Token from msal.
fixes and typing cleanups, see 0.12.0 below
You can now use this in Ionic, Cordova, Browser based process (where CORS is disabled), Outlook Add-in or Mail apps. see ews-js-api-browser
for more detail
(planning to rename this to @ewsjs/ewsjs);
async/await
and move to @ewsjs/*
namespace@ewsjs/xhr
to wrap all exports from @ewsjs/ews
0.9.0
===========================================================================================
OAuthCredentials
@ewsjs/xhr
version to 3.1.0
(dependency audit update)import { ExchangeService, OAuthCredentials, ExchangeVersion } from "ews-javascript-api";
import { EwsOAuthHelper } from "ews-javascript-api/lib/EwsOAuthHelper";
const oAuthHelper = new EwsOAuthHelper({ clientId: '', clientSecret: '', tenantId: '' });
const token = await oAuthHelper.getAppAccessToken();
const ews = new ExchangeService(ExchangeVersion.);
ews.Credentials =new OAuthCredentials(token.accessToken);
await ews.<method>();
you will still need to update expired access token by calling
oAuthHelper.getAppAccessToken()
, you can safely run this when you want to use ews as this can return cached token which is not expired
@ewsjs/ntlm-client
to continue support ntlm with node 18+ (dependency of @ewsjs/xhr
)new Buffer(...)
in the underlying libraryXHRDefault
and ConfigurationApi.ConfigurePromise
exported methods@ewsjs/xhr
to make it easier to useXhrApi
from @ewsjs/xhr
instead of using fetch
WellKnownFolderNames
to be StringPropertyDefinition
type instead of Generic
which microsoft has changed long back. Part of this was fixed by #414 (thanks @klinki)new/fix: #324 Autodiscover is back again, improved and supports DNS fallback using Autodiscover SRV records
new: #320 Allow access to HttpResponseHeaders
, you can use <ExchangeService Instance>.HttpResponseHeaders
to get fresh header from last call to ews service.
<ExchangeService Instance>.OnResponseHeadersCaptured
which is called after each call to service and when headers are returned.Breaking Changes: <ExchangeService>.HttpHeaders
is now Disctionary instance, compatible with c# disctionary. you can no longer do service.HttpHeaders[<header>] = value
. do this instead service.HttpHeaders.Add("header", "value");
fix: #322 you can now delete tasks properly
See older change in CHANGELOG.md
===========================================================================================
EWS managed API for TypeScript/JavaScript - code ported from OfficeDev/ews-managed-api. availbale for nodejs, browser and mobile devices (cordova).
Pluggable XHRApi adapter to replace client (browser) based XHR call with server brokered call (example coming soon). Example Ruby on rails, PHP or any server side framework where c# or nodejs is not available
Works with Office 365/Exchange Online and on-premises Exchange (2007 - 2016)
use SSL for basic authentication NTLM and Cookies Authentication works with nodejs only
NTLM issue with
invalid tagName
gibrish character is due to gzip encoding, see #334.Solution use
gzip: true
inXhrApi({ gzip: true })
constructor options of@ewsjs/xhr
.
All http call is wrapped in promise using default BlueBird promise. You can also interchange compatible promise api.
Code sample from EWS Managed API 2.1. should work with little modificaion to Promise format
You can also leverage new async/await feature of nodejs (>7.0.6) or in TypeScript transpilation with es5/es6 code.
Api document generated using TypeDoc and is hosted at ews-javascript-api.github.io/api. ** outdated Check Wiki for more details
keep track of what is coming in backlog, keep eye on milestones when I start working on it
[sudo] npm install ews-javascript-api
//classic Javascript style
var ews = require('ews-javascript-api');
var exch = new ews.ExchangeService(ews.ExchangeVersion.Exchange2013);
//ES6 TypeScript style
import {ExchangeService, AutodiscoverService, Folder, Item, ExchangeVersion} from "ews-javascript-api";
var exch = new ExchangeService(ExchangeVersion.Exchange2013);
//import ews module
var ews = require('ews-javascript-api');
//create AutodiscoverService object
var autod = new ews.AutodiscoverService(new ews.Uri("https://autodiscover-s.outlook.com/autodiscover/autodiscover.svc"), ews.ExchangeVersion.Exchange2010);
//you can omit url and it will autodiscover the url, version helps throw error on client side for unsupported operations.example - //var autod = new ews.AutodiscoverService(ews.ExchangeVersion.Exchange2010);
//set credential for service
autod.Credentials = new ews.WebCredentials("userName", "password");
//create array to include list of desired settings
var settings = [
ews.UserSettingName.InternalEwsUrl,
ews.UserSettingName.ExternalEwsUrl,
ews.UserSettingName.UserDisplayName,
ews.UserSettingName.UserDN,
ews.UserSettingName.EwsPartnerUrl,
ews.UserSettingName.DocumentSharingLocations,
ews.UserSettingName.MailboxDN,
ews.UserSettingName.ActiveDirectoryServer,
ews.UserSettingName.CasVersion,
ews.UserSettingName.ExternalWebClientUrls,
ews.UserSettingName.ExternalImap4Connections,
ews.UserSettingName.AlternateMailboxes
];
//get the setting
autod.GetUserSettings(["[email protected]", "[email protected]"], settings)
.then(function (response) {
//do what you want with user settings
var tabcount = 0;
var tabs = function () { return ews.StringHelper.Repeat("\t", tabcount); };
console.log(autod.Url.ToString());
//uncoment next line to see full response from autodiscover, you will need to add var util = require('util');
//console.log(util.inspect(response, { showHidden: false, depth: null, colors: true }));
for (var _i = 0, _a = response.Responses; _i < _a.length; _i++) {
var resp = _a[_i];
console.log(ews.StringHelper.Format("{0}settings for email: {1}", tabs(), resp.SmtpAddress));
tabcount++;
for (var setting in resp.Settings) {
console.log(ews.StringHelper.Format("{0}{1} = {2}", tabs(), ews.UserSettingName[setting], resp.Settings[setting]));
}
tabcount--;
}
}, function (e) {
//log errors or do something with errors
});
Example of user availability
var ews = require('ews-javascript-api');
//create ExchangeService object
var exch = new ews.ExchangeService(ews.ExchangeVersion.Exchange2013);
exch.Credentials = new ews.WebCredentials("userName", "password");
//set ews endpoint url to use
exch.Url = new ews.Uri("https://outlook.office365.com/Ews/Exchange.asmx"); // you can also use exch.AutodiscoverUrl
var attendee =[ new ews.AttendeeInfo("[email protected]"), new ews.AttendeeInfo("[email protected]")];
//create timewindow object o request avaiability suggestions for next 48 hours, DateTime and TimeSpan object is created to mimic portion of .net datetime/timespan object using momentjs
var timeWindow = new ews.TimeWindow(ews.DateTime.Now, ews.DateTime.Now.AddDays(2));
exch.GetUserAvailability(attendee, timeWindow, ews.AvailabilityData.FreeBusyAndSuggestions)
.then(function (availabilityResponse) {
//do what you want with user availability
}, function (errors) {
//log errors or do something with errors
});
there is some issues with how react native exposes native browser methods, here are changes needs to be done to us ews-js-api-browser
with react native.
Add following lines to some place before requiring ews-js-api-browser
. you need to use @xmldom/xmldom
and base-64
packages.
if (!global.DOMParser) {
global.DOMParser = require('@xmldom/xmldom').DOMParser;
}
if (!global.atob || !global.btoa) {
global.atob = require('base-64').decode;
global.btoa = require('base-64').encode;
}
Review Core/ExchangeService methods in api document, Any method not marked private oe internal (internal marker is in description of method) is posted and can be used, open issue if it doe snot work
ArchiveItems AutodiscoverUrl BindToGroupItems BindToItems ConvertId ConvertIds CopyItems CreateItems DeleteItems ExpandGroup FindAppointments FindFolders FindItems GetAttachments GetClientAccessToken GetPasswordExpirationDate GetRoomLists GetRooms GetUserAvailability GetUserOofSettings GetUserOofSettings LoadPropertiesForItems MarkAsJunk MoveItems ResolveName SetTeamMailbox SetUserOofSettings SetUserOofSettings SubscribeToPullNotifications SubscribeToStreamingNotifications SubscribeToStreamingNotificationsOnAllFolders SyncFolderHierarchy SyncFolderItems UnpinTeamMailbox UpdateItems GetInboxRules UpdateInboxRules AddDelegates GetDelegates RemoveDelegates UpdateDelegates GetUserRetentionPolicyTags FindConversation FindGroupConversation GetConversationItems GetGroupConversationItems EnableAlwaysCategorizeItemsInConversations DisableAlwaysCategorizeItemsInConversations EnableAlwaysDeleteItemsInConversations DisableAlwaysDeleteItemsInConversations EnableAlwaysMoveItemsInConversations DisableAlwaysMoveItemsInConversations MoveItemsInConversations CopyItemsInConversations DeleteItemsInConversations SetReadStateForItemsInConversations SetRetentionPolicyForItemsInConversations SetFlagStatusForItemsInConversations GetAppManifests GetAppMarketplaceUrl DisableApp InstallApp UninstallApp GetDiscoverySearchConfiguration GetHoldOnMailboxes GetNonIndexableItemDetails GetNonIndexableItemStatistics GetSearchableMailboxes SearchMailboxes SetHoldOnMailboxes
BindToFolder CopyFolder CreateFolder DeleteFolder EmptyFolder FindFolders FindItems Load LoadPropertiesForFolder MarkAllItemsAsRead MarkAllItemsAsUnread RemoveExtendedProperty SetExtendedProperty MoveFolder Save UpdateFolder
ArchiveItem BindToItem CopyItem[s] CreateItem DeleteItem[s] FindAppointments FindItems LoadPropertiesForItems MarkAsJunk MoveItem SendItem Save UpdateItem[s] RemoveExtendedProperty SetExtendedProperty AcceptTentatively [Appointment] AcceptTentatively [Appointment] Decline [Appointment]
AMD module for require.js to be included in build system, bower module and related documentation will be published.
in progress....
Licensed under MIT