
ews-javascript-api
==================
Exchange Web Service in JavaScript/TypeScript.
===========================================================================================
Current State:
* Almost all methods in ExchangeService class is comple with respect to c# counterpart (
based on commit#31951f4
* some method skipped as they are not for client side code or are diaognostic methods.
* Roadmap to Beta:
* ReWrite XHR/Request and Promise see #94
* 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 isnt taking any advantage of.
* Add jsdoc comment to remaining exported class
* Roadmap to 1.0
* fix bugs from Beta
* complete code improvement based on diff from original snapshot
* basic tests to be introduced to prevent breaking changes
* Add documentation with sample code for each operation in ExchangeService methods
* Integrate ntlm and cookies authentication code in main library
* Beyond 1.0
* Add npm based typings support for lates TypeScript based workflow
* minified version for any developer need
* String Null check to improve reliability, TypeScript 2.0 feature
* Complete jsdoc comment in
* Complete code for new features introduced after the snapshot I was working on
* Add OAuth authentication with Azure AD (needs admin created APP in Azure AD)
* Break into components to have better performance and download
* enable non Node scenarios
* trimmed version for Outlook Mail APP supported EWS calls
===========================================================================================
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)
Authentication
* Basic - inbuilt
*
NTLM - using XHRApi adapter
*
Cookies/FBA Authentication with TMG/ISA - using XHRApi adapter
> use SSL for basic authentication
NTLM and Cookies Authentication works with nodejs only
Modules
* commonjs module for NodeJs
AMD module for browser
All http call is wrapped in promise using WinJS promise.
Code sample from
EWS Managed API 2.1. should work with little modificaion to Promise format
Documentation
Api document generated using TypeDoc and is hosted at
ews-javascript-api.github.io/api.
Check
Wiki for more details
keep track of what is coming in
backlog, keep eye on
milestones when I start working on it
Whats new v0.8.0
new: #46 eDiscovery operations
availbale, see MSDN: eDiscovery in EWS* section on this link.aspx#eDisc)
* new:
#120 missing method parameters for SetHoldOnMailboxes operation in c# library, but in EWS operation.
* fix:
#99 - Can't cancel meeting - TypeError
Whats new v0.7.0
new: #46 UserConfiguration operations
availbale, see MSDN: Working with user configuration objects by using the EWS Managed API 2.0*.aspx)
> Caveat: all binary data and XML data should be converted to base64 string, this library assumes all base64 strings where binary data or c# byte[] is used.
Whats new v0.6.2
new: #100 More Item Types implemented*
* fix: #114 - ConversationQueryTraversal returns a soap fault
* fix: #91 - StreamingSubscriptionConnection.OnDisconnect not called for streaming subscription
* fix: #101 - FindItems() not fulfilled/rejected for an unauthorized request
* fix: #109 - Appointment: Recurrence is always null
* fix: #96 - SearchFilter collection not working
* fix: #99 - Can't cancel meeting - TypeError
* fix: #95 - Message body text not working
* fix/PR: #102 - SendCancellationsMode fix enum serialization
* fix: #86 - Issue with sending meeting responses
Whats new v0.6.0 (and fixed in 0.5.1 and 0.5.2)
new: #41 App management operations
availbale, see MSDN: Mail apps for Outlook* section by using EWS in Exchange.aspx#ewsmailapps)
* fix: #64 - small type fixed to prevent error in typing d.ts file
* fix: #69 - Fixed use of ComplexpropertyCollectioin type objects, there were issues in parsing this complex type with different elements in ews operations
* fix: #71 - Fixed
this lexical scope in delegate calls when called by xhr promise.
* fix: #76 - Fixed improper detection of ComplexProperty type and PropertyDefinition type inside PropertySet.
* fix: #83 - Added
ServiceRequestUnauthorizedException class to detect "Unauthorized" exception in case of 401 status code in http call.
SoapFaultDetails.Exception can be checked for this class type in case of 401 exception in xhr call.
Whats new v0.5.0
new: Conversation operations* availbale,
see MSDN: How to: Work with conversations by using EWS in Exchange.aspx)
new: MRM operations* now work,
GetUserRetentionPolicyTags is ready to use
see MSDN: GetUserRetentionPolicyTags operation.aspx)
* fix: #60 - use of
Mailbox object cause error when used withuot
reoutingType parameter, which should is
"SMTP"/null by default. Constructor overloads have now implemented.
* fix: #61 -
AutodiscoverService.GetUserSettings silently crashs when one of the user is not found in Exchange
Whats new v0.4.0
new: InboxRule Operations* now works,
GetInboxRules and
UpdateInboxRules methods on ExchangeService now availbale
see MSDN: How to: Manage Inbox rules by using EWS in Exchange.aspx)
new: Delegate management operations* now work
see MSDN: Delegate access and EWS in Exchange.aspx)
Whats new v0.3.0 (including 0.2.8)
new: Mailbox synchronization* now works,
SyncFolderItems and
SyncFolderHierarchy ExchangeService now availbale
see MSDN for example.aspx)
new: Pull Subscription* should now work
use MSDN example.aspx)
* new:
SetTeamMailbox and
UnpinTeamMailbox ExchangeService methods now availbale. (
SetTeamMailbox does not work with Office 365, Access Denied error, on-prem test is pending) See official MSDN reference for detail
ExchangeService.UnpinTeamMailbox method.aspx)
* new:
GetRooms and
GetRoomLists ExchangeService methods now availbale. See official MSDN reference for detail
ExchangeService.GetRooms method.aspx) and
ExchangeService.GetRoomLists method.aspx)
* new:
ConvertId and
ConvertIds ExchangeService methods now availbale, see MSDN detail at
EWS Identifiers in Exchange.aspx)
* new:
GetClientAccessToken ExchangeService method now availbale, used with "Mail App" management, App management (#41) coming later
* fix:
ImpersonatedUserId bug #34
Whats new v0.2.7 (including 0.2.5 and 0.2.6)
* new: Streaming Notification code updated, see issue #24 for example. More details at
How to: Stream notifications about mailbox events by using EWS in Exchange.aspx)
* ~~new: Pull Subscription should also work
MSDN.aspx)~~ not updated yet, pushed to 0.2.8
* new:
SearchFilter code update. See official MSDN link for examples
How to: Use search filters with EWS in Exchange.aspx)
* new: Some use of
ExtendedPropertyDefinition works, see #23 for an example.
* new:
Grouping class updated, it can be applied on
FindItems
new: AccountLockout detection in failed conenction. Does not work with Office 365*
* improvements:
Contact object related code udpate, fix code errors
* improvement:
SoapFaultDetails updated for improved error handling, most EWS operation not return instance of
SoapFaultDetails in case of any failure, it contains
Exception property with information of failures oe exception in operation.
* fix:
FindItems improvements
* bug fixed where code was not updated to handle correct constructor overload
* SearchFilter can be used
* Grouping can be used
*
Whats new v0.2.3
* Appointment/CalendarItem code update
* Appointment can be created using
new Appointment()
* Appointment can be saved with
Appointment.Save()
* Meeting invitation can be send using
Appointment.Save(SendInvitationsMode.SendToAllAndSaveCopy)
* issue - HTML Body is not working using
Appointment
*
GetUserOofSettings and
SetUserOofSettings on ExchangeService is ready to be used.
* fix: Autodiscover issue fixed, where it throws exception when redirecting to office 365 using 302 redirect from CNAME dns record
Whats new v0.2
* Attachment Operations
* GetAttachment method - load attachment information from Attachemnt or AttachmentId
* Create email message with attachment, sample code in Wiki
Getting Started
install
``
shell
[sudo] npm install ews-javascript-api
`
use
`
javascript
//classic Javascript style
var ews = require('ews-javascript-api');
var exch = new ews.ExchangeService(ExchangeVersion.Exchange2013);
//ES6 TypeScript style
import {ExchangeService, AutodiscoverService, Folder, Item, ExchangeVersion} from "ews-javascript-api";
var exch = new ExchangeService(ExchangeVersion.Exchange2013);
`
Autodiscover user settings
`
javascript
//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.ExchangeCredentials("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(["email1@domain.com", "email2@domain.com"], 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 EWS operations
Example of user availability
`
javascript
var ews = require('ews-javascript-api');
//create ExchangeService object
var exch = new ews.ExchangeService(ews.ExchangeVersion.Exchange2013);
exch.Credentials = new ews.ExchangeCredentials("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("email1@domain.com"), new ews.AttendeeInfo("email2@domain.com")];
//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, new ews.DateTime(ews.DateTime.Now.TotalMilliSeconds + ews.TimeSpan.FromHours(48).asMilliseconds()));
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
});
``
Porting status
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
List of ExchangeService methods available
> 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 \*
\* is for new items in recent update
List of Folder object methods available
> BindToFolder
CopyFolder
CreateFolder
DeleteFolder
EmptyFolder
FindFolders
FindItems
Load
LoadPropertiesForFolder
MarkAllItemsAsRead
MarkAllItemsAsUnread
RemoveExtendedProperty
SetExtendedProperty
MoveFolder
Save
UpdateFolder
List of Item object methods available
>ArchiveItem
BindToItem
CopyItem[s]
CreateItem
DeleteItem[s]
FindAppointments
FindItems
LoadPropertiesForItems
MarkAsJunk
MoveItem
SendItem
Save
UpdateItem[s]
RemoveExtendedProperty
SetExtendedProperty
AcceptTentatively
[Appointment]
AcceptTentatively
[Appointment]
Decline
[Appointment]
Use in Cordova
AMD module for require.js to be included in build system, bower module and related documentation will be published.
Tests
in progress....
License
Licensed under MIT