If you are developing an OfficeJS add-in for Outlook or Outlook Online (OWA) and your project requirements have a need to peek inside distribution lists, you might find that there are two kinds:
Distribution Lists – these are Exchange groups, or mail enabled Active Directory groups. These are managed by the enterprise IT and contain a list of email addresses and/or other distributions lists.
Contact Lists / Private Distribution Lists – these are personal lists created by the user that can contain similar objects.
For an Office Add-in, you must use the makeEwsRequestAsync() command to submit EWS to Exchange. And the specific command you will need to use is ExpandDL to get the members of a DL (or contact list). With regards to the first item in the list above, it is pretty straight forward. For the second item there is this blurb on the page:
Private distribution lists are located in the Contacts folder of a user’s mailbox. Private distribution lists do not have e-mail addresses so their store item identifiers are used in an ExpandDL request. Members of a private distribution list can be any mail-enabled user, contacts or distribution lists from Active Directory, or contacts or private distribution lists from a user’s Contacts folder.
The bold part is key. But where do you get this. When you request a to.getAsync() and receive “Bob’s Favorite People” as a recipient item what do you do with it?
The key is to call the EWS method ResolveNames. When you call this on “Bob’s Favorite People” you will get a return value with PrivateDL and an ItemID (the Exchange Store Item ID in the users Contact folder) that you will then send that ItemId to ExpandDL. Here is what the soap response would look like from ResolveNames:
You can then make your ExpandDL request like this:
The result will be a list of all the email addresses, like this:
NOTE: For now the ResolveNames operation is not supported in my library easyEws. I am working to add it in the coming weeks.
Please let me know if you have any suggestions or questions.
NOTE: I am not an Exchange Web Services (EWS) expert, but have some experience with it through the OfficeJS makeEwsRequestAsync() command. To get the answer for this blog entry, I had to go to a real EWS expert to figure this one out. Many thanks to Dan Bagley (EwsEditor) for his assistance.
I will be presenting a demo at the MVP Summit 2018 for Outlook and also helping with some labs in Excel on the OfficeJS platform. In preparation, I updated my Outlook Sample on my GitHub. This sample was created in VSCode via a Yeoman template.
What the add-in does is a check of all users on the To/CC/BCC line, splits apart any groups (or groups in groups) and then checks to see if any of the user emails are external to your domain. If any external users are found it prompts you with dialog asking if you are sure you want to send:
The updated add-in demonstrates:
The OnSend event
The use of dialogs
And the newly added ExpandDL function for Exchange Web Services through the makeEwsRequestAsync() call.
In this sample, I am using both of my libraries:
easyEws – to help with the ExpandDL call. Updated in a previous post.
I also had to create a set of asynchronous functions and asynchronous recursive function calls to perform this work – which got a tad complex. For now all the code is in the function-file.js, but to help with splitting out all recipients and groups I might build this into a new library. For example, here is the function to recursively call itself asynchronously (splitting groups in groups in groups in groups…):
Anyway, I will be demonstrating this add-in and the functionality required at the MVP Summit. So if you are attending, I hope to see you there.
With recent changes to Exchange Online, the ExpandDL functionality has been added to the makeEwsRequestAsync function. As such this function, which was previously “advertised” in easyEws (but marked as **DO NOT USE**), now functions as designed.
To use the new function:
NOTE: AS of this writing (2/27/2018), this is NOT supported in Exchange 2016 (on-prem). It is to be released with CU9.
This has been slow coming, but I have just released v1.0.7 of easyEws. As per usual, it is on NPM and on GitHub. You can get the latest with the command:
npm update easyews
Or, you can install it into your solution with the command:
npm install easyews
In this version the JSDOC information is now full incorporated so you get great inline help with each command. I enhanced the library so that it works better with inline help and so I changed how the class is setup and exposed. I have updated the README.md on GitHub, but I still am working on examples and such, that will be done later. And I added new functionality, a moveItem command which can be used to move any item from one folder to another. This was a added due to feedback I received on LinkedIn.
Please feel free to reach out to me with any questions or suggestions.