easyEWS

This library makes performing EWS operations from Outlook Mail Web Add-ins via JavaScript much easier.

This project is maintained by davecra

ALERT

This library will be deprcated after FEB 2025 because the makeEwsRequestAsync() function that this library uses will be deprecated by Microsoft and will no longer work. For more information on the functionality, please see the note at the top of this Microsoft article:

Use Exchange Web Services (EWS) from an Outlook add-in

Legacy Exchange tokens are deprecated. Starting February 2025, we’ll begin to turn off legacy Exchange user identity and callback tokens for Exchange Online tenants.

LOGO

Introduction

This library makes performing EWS operations from Outlook Mail Web Add-ins via JavaScript much easier. EWS is quite difficult to perform from JavaScript because you have to format a specific SOAP message in order to submit the request using makeEwsRequestAsync(). However, this is complicated by the fact you then get a SOAP message back that you then have to parse in order to get your result (or error). This library limits your need to call makeEwsRequestAsync() by encapsulating the call in easy to use functions.

NOTE: If you encounter any problems with this library, please submit an issue: https://github.com/davecra/easyEWS/issues.

NOTE: Microsoft official guidance at this point is to no longer use EWS, but rather to use the REST API’s. Some of this functionality (as of this writing: 8/1/2017), is available through REST and some is not. However, to get more informaiton, please see the following link:https://docs.microsoft.com/en-us/outlook/add-ins/use-rest-api

Installation

To install this library, run the following command:

npm -install easyews

Referencing

easyEws comes with both a full (debug) version and a minified version. To access the debug version from node_modules (if your source is in the root of your project):

<script type="text/javascript" src="node_modules/easyews/easyews.js"></script>

To access the minified version from node_modules (if your source is in the root of your project):

<script type="text/javascript" src="node_modules/easyews/easyews.min.js"></script>

easyEws can also be accessed from the following CDN: https://cdn.jsdelivr.net/npm/easyews/easyEws.js

<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/easyews/easyEws.js"></script>

or, the minified version:

<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/easyews/easyEws.min.js"></script>

NOTE: This uses the CDN published through NPM. In the past this pointed to the one on GitHub, but I have had versioning issues where JSDelivr does not update for serveral days or at all with GitHub updates. However, the NPM CDN pointer seems to work much better.

NOTE: If you need to reference a spcific version of EWS, every version is kept and accessible via version number. The following table contains the most recent versions:

Version Url Minified
v1.0.14 https://cdn.jsdelivr.net/npm/easyews@1.0.14/easyEws.js https://cdn.jsdelivr.net/npm/easyews@1.0.14/easyEws.min.js
v1.0.15 https://cdn.jsdelivr.net/npm/easyews@1.0.15/easyEws.js https://cdn.jsdelivr.net/npm/easyews@1.0.15/easyEws.min.js
v1.0.16 https://cdn.jsdelivr.net/npm/easyews@1.0.16/easyEws.js https://cdn.jsdelivr.net/npm/easyews@1.0.16/easyEws.min.js
v1.0.17 https://cdn.jsdelivr.net/npm/easyews@1.0.17/easyEws.js https://cdn.jsdelivr.net/npm/easyews@1.0.17/easyEws.min.js
v1.0.18 https://cdn.jsdelivr.net/npm/easyews@1.0.18/easyEws.js https://cdn.jsdelivr.net/npm/easyews@1.0.18/easyEws.min.js
v1.0.19 https://cdn.jsdelivr.net/npm/easyews@1.0.19/easyEws.js https://cdn.jsdelivr.net/npm/easyews@1.0.19/easyEws.min.js
v1.0.20 https://cdn.jsdelivr.net/npm/easyews@1.0.20/easyEws.js https://cdn.jsdelivr.net/npm/easyews@1.0.20/easyEws.min.js
v1.0.21 https://cdn.jsdelivr.net/npm/easyews@1.0.21/easyEws.js https://cdn.jsdelivr.net/npm/easyews@1.0.21/easyEws.min.js

Follow

Please follow my blog for the latest developments on easyEws. You can find my blog here:

LOGO http://theofficecontext.com

You can use this link to narrow the results only to those posts which relate to this library:

TWITTER You can also follow me on Twitter: @davecra

LINKEDIN And also on LinkedIn: davidcr

Usage

This section is covers how to use easyEws. The following functions are available to call:

sendMailItem

This is a ALL PURPOSE method to send an HTML or Text message to multiple recipients on the TO line with any number of attachments of either Mail Item or File types.

Here are the paramaters for this method:

Here are the parameters for the SendMailFunctionObject:

Example

Here is an example of how to use this method

  /**@type {SimpleAttachmentObject} */
  var att = new SimpleAttachmentObject("welcome_packet.txt", "SGVsbG8gd29ybGQh", "file");
  /**@type {SendMailFunctionObject} */
  var p = new SendMailFunctionObject("Simple Subject", 
                                     "<b>Welcome</b> and hello World!", 
                                     "html", 
                                      ["testing@contoso.com"], 
                                      [att], "sentitems", 
                                      function(result) {
                                        console.log(result);
                                      }, function(error) {
                                        console.log(error);
                                      }, function(debug) {
                                        console.log(debug);
                                      });
  easyEws.sendMailItem(p);

sendPlainTextEmailWithAttachment

This method will send a plain text message to a recipient with a mime message item attachment. This function is very specific, but provides the essential foundation for creating an email with different options.

Here are the paramaters for this method:

Example

Here is an example of how to use this method:

function sendSuspiciousMessage() {
    var item = Office.context.mailbox.item;
    var itemId = item.itemId;
    easyEws.getMailItemMimeContent(itemId, function(mimeContent) {
    	var toAddress = "davidcr@outlook.com";
    	easyEws.sendPlainTextEmailWithAttachment("Suspicious Email Alert",
                                                 "A user has forwarded a suspicious email",
                                                 toAddress,
                                                 "Suspicious_Email.eml",
                                                 mimeContent,
                                                function(result) { console.log(result); },
                                                function(error) { console.log(error); }, 
                                                function (debug) { console.log(debug); });
  }, function(error) { console.log(error); }, function(debug) { console.log(debug); });
}

getMailItemMimeContent

This method will return the MIME content of a specific mail item.

Here are the paramters for this method:

Example

Here is an example of how to use this method:

function sendSuspiciousMessage() {
	var item = Office.context.mailbox.item;
	itemId = item.itemId;
	mailbox = Office.context.mailbox;
	easyEws.getMailItemMimeContent(itemId, function(mimeContent) {
		var toAddress = "securityteam@somwhere.local";
		easyEws.sendPlainTextEmailWithAttachment("Suspicious Email Alert",
							 "A user has forwarded a suspicious email",
							 toAddress,
							 "Suspicious_Email.eml",
							 mimeContent,
							 function(result) { console.log(result); },
							 function(error) { console.log(error); }, 
							 function (debug) { console.log(debug); }
		);
	 }, function(error) { console.log(error); },
	    function(debug) { console.log(debug); } 
	);
}

updateEwsHeader

This method will update the mail transport (x-headers) in the selected message. The message must be saved into the mail store for this to work.

NOTE: If you try to perform this on Outlook 2016 / full-windows-client, the settings may not stick if you are running in cached mode. This is by default. The only way for this to work is to wait for 30 seconds to a minute. This problem DOES NOT occur with Outlook in online mode and in Outlook Web Access (OWA) or Outlook Online (Office 365).

Here are the paramters for this method:

Example

Here is an example of how to use this method:

// first, we have to save the item to the drafts folder, which will get us the 
// Exchange EWS_ID of the item. We then use that ID to update the header.
Office.context.mailbox.item.saveAsync(function (idResult) {
    	var id = idResult.value;
	// now that we have the ID of the mail item, we update the header
	easyEws.updateEwsHeader(id, "x-myheader", value, false, function () {
	    console.log("x-header has been set.");
	}, function(error) {
	    console.log(error);
	}, function(debug) {
	    console.log(debug);
	});
});

getFolderItemIds

This method will return an array of item IDs for all the items found in a particular folder. If you need the number of items in a folder you can get the array count. If you need to find a specific item you can then use the ID’s to make the getMailItem() method.

Here are the paramaters for this method:

Example

Here is an example of how to use this method:

Example is TBD.

getMailItem

This method will get all the details of a mail item and store it in a MailItem object.

NOTE: The MailItem object right now is very primitive only surfacing a few of the properties. If more proeprties are needed, please contact me.

Here are the parameters for this method:

Example

Here is an example of how to use this method:

Example is TBD.

expandGroup

(2/27/2018) This does not function in Exchange 2016 / On-Prem (TBD in CU9).

This method will take a group name and split it one level to constituent users and groups. It is not recursive, so if you need to split multiple groups within groups, you will need to call this function multiple times.

Here are the paramters for this method:

Example

Here is an example of how to use this method:

/**
 * Breaks upp all the groups on the to/cc/bcc lines of the message
 * and reports the total number of member affected.
 * @param {Office.AddinCommands.Event} event 
 */
function breakGroups(event) {
  $(document).ready(function () {
    var mailItem = Office.context.mailbox.item;
    // Get all the recipients for the composed mail item
    easyEws.getAllRecipientsAsync(mailItem, 
    /**
     * Returns a groups of users[] and groups[] we only
     * care about the groups here and will expand them
     * @param {Office.EmailAddressDetails[]} users 
     * @param {Office.EmailAddressDetails[]} groups 
     */
    function(users,groups) {
      var allMembers = [];
      // loop through all the groups found
      for(var i=0;i<groups.length;i++) {
        var groupEmail = groups[i].emailAddress;
        easyEws.expandGroup(groupEmail, function(members) {
          console.log("Split group " + groupEmail + " with " + members.length + " member(s)");
          $.each(members, function(index, item) { allMembers.push(item); });
          // on the last item, notify the user
          if(i >= groups.length) {
            // NOTE: using OfficeJS.dialogs (https://github.com/davecra/officejs.dialogs)
            Alert.Show("All groups have been split.\nThere are " + allMembers.length + " members.", 
            function() {
              // button event complete
              event.completed();
            });
          }
        }, function(error) {
          console.log("ERROR: " + error.description);
          event.completed();
        }, function(debug) {
          // DEBUG OUTPUT:
          // displays the SOAP to EWS
          // displays the SOAP back from EWS
          console.log(debug);
        });
      }
    });
  });
}

splitGroupsAsync

This method takes an array of email addresses (as strings) for Distribution Groups and makes recursive asynchronous calls to expandGroup to return a list of unique users found inside each group, and even groups within groups (up to 100 groups total).

NOTE: This function will automatically exit after 100 groups (including groups within groups) have been parsed. This is to prevent a possible hang when encountering circular groups.

Here are the paramters for this method:

Example

Here is an example of how to use this method:

/**
 * Breaks upp all the groups on the to/cc/bcc lines of the message
 * and reports the total number of member affected.
 * @param {Office.AddinCommands.Event} event 
 */
function breakGroups(event) {
  $(document).ready(function () {
    var mailItem = Office.context.mailbox.item;
    // Get all the recipients for the composed mail item
    easyEws.getAllRecipientsAsync(mailItem, 
    /**
     * Returns a groups of users[] and groups[] we only
     * care about the groups here and will expand them
     * @param {Office.EmailAddressDetails[]} users 
     * @param {Office.EmailAddressDetails[]} groups 
     */
    function(users,groups) {
      /** @type {string[]} */
      var groupList = [];
      $.each(groups, function(index, item) { groupList.push(item.emailAddress); })
      easyEws.splitGroupsAsync(groupList, 
      /**
       * Success callback from splitGroupAsync, returns an array
       * of all the users mailboxes found in an array
       * @param {MailboxUser[]} members 
       */
      function(members) {
        console.log("Split " + groups.length + " groups containing " + members.length + " member(s)");
        // NOTE: using OfficeJS.dialogs (https://github.com/davecra/officejs.dialogs)
        Alert.Show("All groups have been split.\nThere are " + members.length + " members.", 
        function() {
          // button event complete
          event.completed();
        });
      }, function(error) {
        console.log("ERROR: " + error.description);
        event.completed();
      }, function(debug) {
        // DEBUG OUTPUT:
        // displays the SOAP to EWS
        // displays the SOAP back from EWS
        console.log(debug);
      });
    });
  });
}

getAllRecipientsAsync

This method accepts the current ComposeItem and then parse the To/CC/BCC lines and returns a list of unique users (as an array of MailBoxUser) and a unique list of groups (as an array of MailBoxUser). This function is useful in conjunction with the splitGroupsAsync() method.

Here are the parameters of the method:

Example

Here is an example of how to use this method:

/**
 * Returns the total number of users on the to/cc/bcc lines
 * @param {Office.AddinCommands.Event} event 
 */
function getAllUsers(event) {
  $(document).ready(function () {
    var mailItem = Office.context.mailbox.item;
    // Get all the recipients for the composed mail item
    easyEws.getAllRecipientsAsync(mailItem, 
    /**
     * Returns a groups of users[] and groups[] we only
     * care about the groups here and will expand them
     * @param {Office.EmailAddressDetails[]} users 
     * @param {Office.EmailAddressDetails[]} groups 
     */
    function(users,groups) {
      Alert.Show("There are " + users.length + " user(s) and " + groups.length + " group(s) being directly address.", 
      function() {
        event.completed();
      });
    });
  });
}

findConversationItems

This method will return all the related itemID’s in a specific conversation. If you need to find a specific item you can then use the ID’s to make the getMailItem() method.

Here are the paramaters for this method:

Example

Here is an example of how to use this method:

var conversationId = Office.context.mailbox.item.conversationId;
easyEws.findConversationItems(conversationId, function (itemArray) {
	if (itemArray === null || itemArray.length === 0) {
		console.log("No_coversation_items_found");
		return;
	}
	// we will grab the first item as the newest
	var mostRecentId = itemArray[0];
	console.log("Most recent conversation is: " + mostRecentId);
	}, function (error) {
		console.log(error);
	}, function (debug) {
		console.log(debug);
	});

getSpecificHeader

This method will return a specific mail header (x-header) value for a specific mail item.

Here are the paramters for this method:

Example

Here is an example of how to use this method:

easyEws.getSpecificHeader(id, "x-myheader", "String", function (result) {
	if (result === null || result === "") {
		console.log("not_found");
	} else {
		console.log("Result: " + result);
	}
}, function (error) {
	console.log(error);
}, function (debug) {
	console.log(debug);
});

getEwsHeaders

This method will get return all the Internet Message Headers (x-headers) for a given mail item.

Here are the parameters for this method:

Example

Here is an example of how to use this method:

easyEws.getEwsHeaders(id, function (headersDictionary) {
	var classificationResult = "";
	headersDictionary.forEach(function (key, value) {
		if (key.toLowerCase().startsWith("x-myheader")) {
			// success
			completeCallback(value);
			return;
		}
	});
	completeCallback("no_header_found");
}, function (error) {
	console.log("Failed to get EWS Headers.\n" + error);
}, function (debug) {
	console.log("getEwsHeaders: " + debug);
});

updateFolderProperty

This method will update a specific named property on a MAPI folder object in the Exchange message store.

Here are the paramters for this method:

Example

Here is an example of how to use this method:

Example is TBD.

getFolderProperty

This method will get the value of a specific named property on an API folder object in the Exchange message store.

Here are the paramters for this method:

Example

Here is an example of how to use this method:

Example is TBD.

getFolderId

Gets the folder ID for a specific names MAPI folder in the Excahnge mail store.

Here are the parameters for this method:

Example

Here is an example of how to use this method:

Example is TBD.

moveItem

Moves an item to the specified MAPI folder in the Exchange store.

Here are the paramters for this method:

Example

Here is an example of how to use this method:

    // moves the selected item in a Read add-in to 
    // the deleted items folder...
    var item = Office.context.mailbox.item;
    var itemId = item.itemId;
    easyEws.moveItem(itemId, "deleteditems", function() {
      console.log("success");
    }, function(error) {
      console.log(error);
    });

resolveRecipient

Resolves a recipient.

Here are the parameters for this method:

Example

Here is an example of how to use this method:

async function run() {
    var msg = Office.context.mailbox.item;
    msg.to.getAsync(function(asyncResult) {
        if(asyncResult.status == Office.AsyncResultStatus.Failed) {
            $("#recipientResult").text(asyncResult.error);
        } else {
            /** @type {Office.EmailAddressDetails[]} */
            var recips = asyncResult.value;
            // are there any recipients at all
            if(recips == null || recips.length == 0) {
                $("#recipientResult").html("NO RECIPIENTS");
            } else {
                /** @type {string} */
                var info  = "<br/>DISPLAY NAME: " + recips[0].displayName + "<br/>" +
                            "EMAIL_ADDRESS: " + recips[0].emailAddress + "<br/>" +
                            "RECIPIENT_TYPE: " + recips[0].recipientType;
                easyEws.resolveRecipient(recips[0].emailAddress, function(result) {
                    if(result == null || result.length == 0) {
                        info += "<br/>UNRESOLVED</br>";
                    } else {
                        info += "<br/>RESOLVED: " + result[0].MailBoxType;
                        info += "<br/>RESOLVED EMAIL: " + result[0].EmailAddress;
                    }
                    // write tot he form
                    $("#recipientResult").html(info);
                }, function(error) {
                    $("#recipientResult").text(error);
                }, function(debug) {
                    $("#debugResult").text(debug)
                });
            }
        }
    });
}

getParentId

Gets the Id for the parent of the specified mail item

Here are the parameters for this method:

Example

Here is an example of how to use this method:

Office.cast.item.toMessageCompose(Office.context.mailbox.item).saveAsync(function (idResult) {
  var childId = idResult.value;
  easyEws.getParentId(childId, function (parentId) {
      if(parentId !== null) {
        console.log("The parent ID is: " + parentId);
      } else {
        console.log("The item has no parent, or it could not be found.");
      }
    }, function (error) {
      console.log(error);
    }, function (debug) {
      console.log(debug);
  });
});