{"id":14985802,"url":"https://github.com/gautamsi/ews-javascript-api","last_synced_at":"2025-05-14T23:02:10.245Z","repository":{"id":24665584,"uuid":"28075973","full_name":"gautamsi/ews-javascript-api","owner":"gautamsi","description":"EWS API for TypeScript/JavaScript - ported from OfficeDev/ews-managed-api - node, cordova, meteor, Ionic, Electron, Outlook Add-Ins","archived":false,"fork":false,"pushed_at":"2025-03-28T14:59:37.000Z","size":8722,"stargazers_count":287,"open_issues_count":68,"forks_count":73,"subscribers_count":18,"default_branch":"master","last_synced_at":"2025-05-05T18:13:19.524Z","etag":null,"topics":["cordova","ews","ews-api","exchange-web-services","ionic","ionic3","meteor","outlook-addin"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gautamsi.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2014-12-16T07:38:46.000Z","updated_at":"2025-03-27T04:17:44.000Z","dependencies_parsed_at":"2024-06-18T12:40:30.179Z","dependency_job_id":"1754a86e-6c80-4803-9308-47be48e747d1","html_url":"https://github.com/gautamsi/ews-javascript-api","commit_stats":{"total_commits":354,"total_committers":24,"mean_commits":14.75,"dds":0.3615819209039548,"last_synced_commit":"67c19206a7ea9054808f77fb0f64c5f75ac1f16c"},"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gautamsi%2Fews-javascript-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gautamsi%2Fews-javascript-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gautamsi%2Fews-javascript-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gautamsi%2Fews-javascript-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gautamsi","download_url":"https://codeload.github.com/gautamsi/ews-javascript-api/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254243353,"owners_count":22038044,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cordova","ews","ews-api","exchange-web-services","ionic","ionic3","meteor","outlook-addin"],"created_at":"2024-09-24T14:11:42.403Z","updated_at":"2025-05-14T23:02:10.222Z","avatar_url":"https://github.com/gautamsi.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"ews-javascript-api \n==================\n## Exchange Web Service in JavaScript/TypeScript.\n\n## Support\nContact @gautamsi for support. Use [![Gitter](https://badges.gitter.im/gautamsi/ews-javascript-api.svg)](https://gitter.im/gautamsi/ews-javascript-api?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge) for 1:1 support and paid support. Also looking for sponsors to fund remaining development on this. \n\n===========================================================================================    \n## Office 365 OAuth Support is built in\nsee 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.\n\n## March 2023 Update:\nfixes and typing cleanups, see 0.12.0 below\n\n## July 2019 Update:  \nYou 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`](https://github.com/gautamsi/ews-js-api-browser) for more detail\n\n\u003e(planning to rename this to @ewsjs/ewsjs);\n\n# Current State:\n* Almost all methods in ExchangeService class is comple with respect to c# counterpart ([based on commit#31951f4 ](https://github.com/OfficeDev/ews-managed-api/commit/31951f456519786e41232fa9ff6a3ab20b56cac3)\n    * some method skipped as they are not for client side code or are diaognostic methods. \n* Roadmap to 1.0 Beta:\n    * ~~ReWrite XHR/Request and Promise see #94~~ done\n    * ~~Rewrite Autodiscover code with fresh Promise approach, this code was my work in very beginning and poorly written, strategy and TypeScript features improved over time which this code isn't taking any advantage of.~~ done\n    * use `async/await` and move to `@ewsjs/*` namespace\n    * chain `@ewsjs/xhr` to wrap all exports from `@ewsjs/ews`\n    * Add jsdoc comment to remaining exported class\n* Roadmap to 1.0\n    * fix bugs from Beta\n    * complete code improvement based on diff from original snapshot\n    * basic tests to be introduced to prevent breaking changes\n    * Add documentation with sample code for each operation in ExchangeService methods\n    * Integrate ntlm and cookies authentication code in main library \n* Beyond 1.0 \n    * ~Add npm based typings support for lates TypeScript based workflow~ completed in `0.9.0`\n    * minified version for any developer need \n    * String Null check to improve reliability, TypeScript 2.0 feature\n    * Complete jsdoc comment in \n    * Complete code for new features introduced after the snapshot I was working on\n    * Add OAuth authentication with Azure AD (needs admin created APP in Azure AD)\n    * Break into components to have better performance and download\n    * enable non Node scenarios\n    * trimmed version for Outlook Mail APP supported EWS calls  \n\n===========================================================================================\n\n# Whats new v0.15.0\n* Added helper class for Exchange Online/Office 365 OAuth with Exchange RBAC with Apps Support (This is latest Microsoft Guideline)\n    - This RBAC method is APP only which uses Client Credential Flow and not user specific token\n    - You can still get user specific access token by delegation and pass token to `OAuthCredentials`\n* updated `@ewsjs/xhr` version to `3.1.0` (dependency audit update)\n\n```ts\nimport { ExchangeService, OAuthCredentials, ExchangeVersion } from \"ews-javascript-api\";\nimport { EwsOAuthHelper } from \"ews-javascript-api/lib/EwsOAuthHelper\";\n\nconst oAuthHelper = new EwsOAuthHelper({ clientId: '', clientSecret: '', tenantId: '' });\nconst token = await oAuthHelper.getAppAccessToken();\nconst ews = new ExchangeService(ExchangeVersion.);\news.Credentials =new OAuthCredentials(token.accessToken);\nawait ews.\u003cmethod\u003e();\n```\n\u003e 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\n\n# Whats new v0.14.0\n* Updated implementation of `@ewsjs/ntlm-client` to continue support ntlm with node 18+ (dependency of `@ewsjs/xhr`)\n* This fixes latest support for ntlm with node 18/20+\n* This also fixes security warning of `new Buffer(...)` in the underlying library\n\n\n# Whats new v0.13.0 **BREAKING CHANGES**\n* Security update: removed fetch and bluebird dependency\n* removed `XHRDefault` and `ConfigurationApi.ConfigurePromise` exported methods\n* Exported XHRApi from `@ewsjs/xhr` to make it easier to use\n* Using default implementation of `XhrApi` from `@ewsjs/xhr` instead of using `fetch`\n\n\n# Whats new v0.12.0\n* fixed `WellKnownFolderNames` to be `StringPropertyDefinition` type instead of `Generic` which microsoft has changed long back. Part of this was fixed by #414 (thanks @klinki)\n* fixes #416 and also cleans up other typing issues\n* Security update: updated all dependency to latest version.\n\n\n# Whats new v0.11.0\n* **BREAKING** dependencies upgraded to latest version of commonjs module (still avoiding pure esm modules). The code is now compiled to es6 target, must use nodejs version \u003e= 10\n* Security update: updated all dependency to latest version.\n\n\n# Whats new v0.10.0\n* new/fix: #324 Autodiscover is back again, improved and supports DNS fallback using Autodiscover SRV records\n* new: #320 Allow access to `HttpResponseHeaders`, you can use `\u003cExchangeService Instance\u003e.HttpResponseHeaders` to get fresh header from last call to ews service.\n  *  you can also add a delegate (callback) for `\u003cExchangeService Instance\u003e.OnResponseHeadersCaptured` which is called after each call to service and when headers are returned.\n\n* **Breaking Changes**:  `\u003cExchangeService\u003e.HttpHeaders` is now Disctionary instance, compatible with c# disctionary. you can no longer do `service.HttpHeaders[\u003cheader\u003e] = value`. do this instead `service.HttpHeaders.Add(\"header\", \"value\"); `\n\n* fix: #322 you can now delete tasks properly\n\n\n[See older change in CHANGELOG.md](./CHANGELOG.md)\n\n===========================================================================================\n\nEWS managed API for TypeScript/JavaScript - code ported from OfficeDev/ews-managed-api. availbale for nodejs, browser and mobile devices (cordova).  \n\nPluggable 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\n\nWorks with **Office 365/Exchange Online** and on-premises Exchange (2007 - 2016)\n\n## Authentication\n* Basic - inbuilt\n* OAuth - inbuilt (see https://stackoverflow.com/a/43785262/5884960 for more details on how to use.)\n* NTLM and NTLMv2 - using [@ewsjs/xhr](https://github.com/ewsjs/xhr) \n* Cookies/FBA Authentication with TMG/ISA - using [@ewsjs/xhr](https://github.com/ewsjs/xhr) \n\n\u003e use SSL for basic authentication  \nNTLM and Cookies Authentication works with nodejs only\n\n\u003e **NTLM** issue with `invalid tagName` gibrish character is due to gzip encoding, see #334. \n\u003e \n\u003e **Solution** use `gzip: true` in `XhrApi({ gzip: true })` constructor options of `@ewsjs/xhr`.\n\n## Modules\n* commonjs module for NodeJs\n* AMD module for other scenarios* (not documented yet)\n\n~~All http call is wrapped in promise using default BlueBird promise.  You can also interchange compatible promise api.~~\nCode sample from [EWS Managed API 2.1.](https://msdn.microsoft.com/en-us/library/office/jj536567.aspx) should work with little modificaion to Promise format   \n\n## async/await latest nodejs\nYou can also leverage new async/await feature of nodejs (\u003e7.0.6) or in TypeScript transpilation with es5/es6 code.  \n\n\n## Documentation\nApi document generated using TypeDoc and is hosted at [ews-javascript-api.github.io/api](http://ews-javascript-api.github.io/api).  ** outdated\nCheck [Wiki](https://github.com/gautamsi/ews-javascript-api/wiki) for more details\n\nkeep track of what is coming in [backlog](https://github.com/gautamsi/ews-javascript-api/milestones/backlog), keep eye on [milestones](https://github.com/gautamsi/ews-javascript-api/milestones) when I start working on it \n\n\n# Getting Started\n## install\n```shell\n[sudo] npm install ews-javascript-api\n``` \n\n## use\n```javascript\n//classic Javascript style\nvar ews = require('ews-javascript-api');\nvar exch = new ews.ExchangeService(ews.ExchangeVersion.Exchange2013);\n//ES6 TypeScript style\nimport {ExchangeService, AutodiscoverService, Folder, Item, ExchangeVersion} from \"ews-javascript-api\";\nvar exch = new ExchangeService(ExchangeVersion.Exchange2013);\n```\n## Autodiscover user settings (** Working again as of 0.10 **)\n```javascript\n//import ews module\nvar ews = require('ews-javascript-api');\n//create AutodiscoverService object\nvar autod = new ews.AutodiscoverService(new ews.Uri(\"https://autodiscover-s.outlook.com/autodiscover/autodiscover.svc\"), ews.ExchangeVersion.Exchange2010);\n//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);\n//set credential for service\nautod.Credentials = new ews.WebCredentials(\"userName\", \"password\");\n//create array to include list of desired settings\nvar settings = [\news.UserSettingName.InternalEwsUrl,\news.UserSettingName.ExternalEwsUrl,\news.UserSettingName.UserDisplayName,\news.UserSettingName.UserDN,\news.UserSettingName.EwsPartnerUrl,\news.UserSettingName.DocumentSharingLocations,\news.UserSettingName.MailboxDN,\news.UserSettingName.ActiveDirectoryServer,\news.UserSettingName.CasVersion,\news.UserSettingName.ExternalWebClientUrls,\news.UserSettingName.ExternalImap4Connections,\news.UserSettingName.AlternateMailboxes\n];\n//get the setting\nautod.GetUserSettings([\"email1@domain.com\", \"email2@domain.com\"], settings)\n.then(function (response) {\n    //do what you want with user settings    \n    var tabcount = 0;\n    var tabs = function () { return ews.StringHelper.Repeat(\"\\t\", tabcount); };\n    console.log(autod.Url.ToString());\n\t//uncoment next line to see full response from autodiscover, you will need to add var util = require('util');\n\t//console.log(util.inspect(response, { showHidden: false, depth: null, colors: true }));\n    for (var _i = 0, _a = response.Responses; _i \u003c _a.length; _i++) {\n        var resp = _a[_i];\n        console.log(ews.StringHelper.Format(\"{0}settings for email: {1}\", tabs(), resp.SmtpAddress));\n        tabcount++;\n        for (var setting in resp.Settings) {\n            console.log(ews.StringHelper.Format(\"{0}{1} = {2}\", tabs(), ews.UserSettingName[setting], resp.Settings[setting]));\n        }\n        tabcount--;\n    }\n}, function (e) {\n    //log errors or do something with errors\n});\n```\n\n## Example EWS operations\nExample of user availability\n```javascript\nvar ews = require('ews-javascript-api');\n//create ExchangeService object\nvar exch = new ews.ExchangeService(ews.ExchangeVersion.Exchange2013);\nexch.Credentials = new ews.WebCredentials(\"userName\", \"password\");\n//set ews endpoint url to use\nexch.Url = new ews.Uri(\"https://outlook.office365.com/Ews/Exchange.asmx\"); // you can also use exch.AutodiscoverUrl\n\nvar attendee =[ new ews.AttendeeInfo(\"email1@domain.com\"), new ews.AttendeeInfo(\"email2@domain.com\")];\n//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\nvar timeWindow = new ews.TimeWindow(ews.DateTime.Now, ews.DateTime.Now.AddDays(2)); \nexch.GetUserAvailability(attendee, timeWindow, ews.AvailabilityData.FreeBusyAndSuggestions)\n.then(function (availabilityResponse) {\n    //do what you want with user availability\n}, function (errors) {\n    //log errors or do something with errors\n});\n        \n```\n\n# Use with React Native\n\nthere 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. \n    Add following lines to some place before requiring `ews-js-api-browser`. you need to use `@xmldom/xmldom` and `base-64` packages.\n```js\nif (!global.DOMParser) {\n    global.DOMParser = require('@xmldom/xmldom').DOMParser;\n}\nif (!global.atob || !global.btoa) {\n    global.atob = require('base-64').decode;\n    global.btoa = require('base-64').encode;\n}\n```\n\n# Porting status\n\nReview 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\n\n## List of ExchangeService methods available  \n\u003e ArchiveItems  \nAutodiscoverUrl  \nBindToGroupItems  \nBindToItems  \nConvertId   \nConvertIds   \nCopyItems  \nCreateItems  \nDeleteItems  \nExpandGroup  \nFindAppointments  \nFindFolders  \nFindItems  \nGetAttachments  \nGetClientAccessToken   \nGetPasswordExpirationDate  \nGetRoomLists  \nGetRooms   \nGetUserAvailability  \nGetUserOofSettings  \nGetUserOofSettings   \nLoadPropertiesForItems  \nMarkAsJunk  \nMoveItems  \nResolveName  \nSetTeamMailbox   \nSetUserOofSettings \nSetUserOofSettings   \nSubscribeToPullNotifications   \nSubscribeToStreamingNotifications   \nSubscribeToStreamingNotificationsOnAllFolders  \nSyncFolderHierarchy   \nSyncFolderItems  \nUnpinTeamMailbox   \nUpdateItems  \nGetInboxRules   \nUpdateInboxRules   \nAddDelegates   \nGetDelegates  \nRemoveDelegates   \nUpdateDelegates   \nGetUserRetentionPolicyTags    \nFindConversation   \nFindGroupConversation   \nGetConversationItems   \nGetGroupConversationItems   \nEnableAlwaysCategorizeItemsInConversations   \nDisableAlwaysCategorizeItemsInConversations   \nEnableAlwaysDeleteItemsInConversations   \nDisableAlwaysDeleteItemsInConversations   \nEnableAlwaysMoveItemsInConversations   \nDisableAlwaysMoveItemsInConversations   \nMoveItemsInConversations   \nCopyItemsInConversations   \nDeleteItemsInConversations   \nSetReadStateForItemsInConversations   \nSetRetentionPolicyForItemsInConversations   \nSetFlagStatusForItemsInConversations    \nGetAppManifests    \nGetAppMarketplaceUrl   \nDisableApp   \nInstallApp   \nUninstallApp   \nGetDiscoverySearchConfiguration   \nGetHoldOnMailboxes   \nGetNonIndexableItemDetails   \nGetNonIndexableItemStatistics   \nGetSearchableMailboxes   \nSearchMailboxes   \nSetHoldOnMailboxes   \n\n\n## List of Folder object methods available\n\n\u003e BindToFolder  \nCopyFolder  \nCreateFolder  \nDeleteFolder  \nEmptyFolder  \nFindFolders  \nFindItems  \nLoad  \nLoadPropertiesForFolder  \nMarkAllItemsAsRead  \nMarkAllItemsAsUnread  \nRemoveExtendedProperty  \nSetExtendedProperty  \nMoveFolder  \nSave  \nUpdateFolder \n\n## List of Item object methods available\n\n\u003eArchiveItem  \nBindToItem  \nCopyItem[s]  \nCreateItem  \nDeleteItem[s]  \nFindAppointments  \nFindItems  \nLoadPropertiesForItems  \nMarkAsJunk  \nMoveItem  \nSendItem  \nSave  \nUpdateItem[s]   \nRemoveExtendedProperty  \nSetExtendedProperty  \nAcceptTentatively  *[Appointment]*  \nAcceptTentatively  *[Appointment]*  \nDecline            *[Appointment]*   \n\n\n## Use in Cordova\nAMD module for require.js to be included in build system, bower module and related documentation will be published.\n\n\n# Tests\nin progress....\n\n\n# License\nLicensed under MIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgautamsi%2Fews-javascript-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgautamsi%2Fews-javascript-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgautamsi%2Fews-javascript-api/lists"}