Updating X-Headers using EWS in Mail Apps

UPDATE (3/1/2021): This solution probably does not work with the updated Office templates that do not have an “app” object defined. You would need to add code like this:

[code language="javascript"]
var app = {};
[/code]

A better option is to use the “updateEwsHeader()” function from my easyEws library.

Transport headers are a very useful tool to help pass application settings from one user mailbox to another. It is also useful in some rules on transport and edge servers to determine how to treat a specific message. While manipulating these headers is easier in Outlook (full client) doing this from a Mail App is a little less clear.

The following code is how I managed to get this to work. First, you have to SAVE the mail item so that you can get a EWS ID. Once you get the ID, we then build the soap message (I declared this in the ‘app’ namespace). Once we have the SOAP message we then make the EWS call.

NOTE: I am using the window.alert() which you can find how to use here.

[code language="javascript"]
    function setXHeader() {

        // first save the item
        Office.cast.item.toItemCompose(Office.context.mailbox.item).saveAsync(function (composeId)
        {
            var id = composeId.value;

            // update the x-headers
            var xml = app.updateXHeaderSoap(id, "X-Test", "ValueHere");
            Office.context.mailbox.makeEwsRequestAsync(xml, function (ewsResult) {
                if (ewsResult.status != "succeeded") {
                    window.alert("Unable to attach x-headers.\n" + ewsResult.error.message);
                }
            });
        });
    }

        // updates the x-headers in the mail item
        // SEE: https://msdn.microsoft.com/en-us/library/office/dn596091(v=exchg.150).aspx
        app.updateXHeaderSoap = function (id, property, value) {
            var soap =
                '<UpdateItem MessageDisposition="SaveOnly" ConflictResolution="AlwaysOverwrite"' +
                '            xmlns="http://schemas.microsoft.com/exchange/services/2006/messages">' +
                '   <ItemChanges>' +
                '       <t:ItemChange>' +
                '           <t:ItemId Id="' + id + '"/>' +
                '           <t:Updates>' +
                '               <t:SetItemField>' +
                '                   <t:ExtendedFieldURI DistinguishedPropertySetId="InternetHeaders"' +
                '                                       PropertyName="' + property + '"' +
                '                                       PropertyType="String" />' +
                '                   <t:Message>' +
                '                       <t:ExtendedProperty>' +
                '                           <t:ExtendedFieldURI DistinguishedPropertySetId="InternetHeaders"' +
                '                                               PropertyName="' + property + '"' +
                '                                               PropertyType="String" />' +
                '                           <t:Value>' + value + '</t:Value>' +
                '                       </t:ExtendedProperty>' +
                '                   </t:Message>' +
                '               </t:SetItemField>' +
                '           </t:Updates>' +
                '       </t:ItemChange>' +
                '   </ItemChanges>' +
                '</UpdateItem>';

            return app.getSoapHeader(soap);
        };

 app.getSoapHeader = function(request) {
         var result =
             '<?xml version="1.0" encoding="utf-8"?>' +
             '<soap:Envelope xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance' +
             '               xmlns:xsd=http://www.w3.org/2001/XMLSchema' +
             '               xmlns:m=http://schemas.microsoft.com/exchange/services/2006/messages' +
             '               xmlns:soap=http://schemas.xmlsoap.org/soap/envelope/' +
             '               xmlns:t=http://schemas.microsoft.com/exchange/services/2006/types>' +
             '   <soap:Header>' +
             '       <RequestServerVersion Version="Exchange2013" xmlns=http://schemas.microsoft.com/exchange/services/2006/types soap:mustUnderstand="0" />' +
             '   </soap:Header>' +
             '   <soap:Body>' + request + '</soap:Body>' +
             '</soap:Envelope>';
         return result;
     };
[/code]