How to forward an email in a Mail Add-in using Exchange Web Services

If you come from a background in desktop COM add-ins or the Outlook Object Model, you’d think forwarding an email with the new Apps for Office Office Add-ins framework would be a piece of cake.  Like:

myForward = mySource.Forward;
myForward.To = "Eddie@IronMaiden.com";
myForward.Send;

You’ll be shocked at how much code is involved to do this with Office for JavaScript!  Or if you know the Mailbox API well enough, you may be wondering why there is Message.displayReplyForm but no displayForwardForm (feel free to request this feature here!). Regardless, we can still use Exchange Web Services (EWS) and thankfully what we need to do is amongst the supported list of EWS operations.

I won’t go into the details of creating the project from scratch since the source code for this project is available, but if you want to rebuild this then see this article for some guidance.  Otherwise, the basic requirements are:

  • Enabling the Add-in for read messages only
  • Grant ‘Read write mailbox permissions’ to the Add-in

And the basic flow is this:

  • Call GetItem (EWS) to get the ChangeKey from the source email that will be forwarded
  • Call CreateItem (EWS) and pass the ChangeKey and the list of email address that we want to forward the email to

We don’t need any activation rules, so our app manifest will be very simple:



		

The UI will be simple, and provide some HTML controls to set some values in the email that we are forwarding:

2015-11-15_19-23-10

So let’s do a quick code walkthrough!

Clicking the Forward button will fire the beginForwardAnEmail() function in AppRead/Home/Home.js:

[crayon-5f8fbbe18e887253378866/]

The important bit in this function is the call to the Mailbox.makeEwsRequestAsync method, which will call the GetItem method in EWS.  But first we need to build the XML fragment we pass as our first parameter, via our getItemDataRequest method:

[crayon-5f8fbbe18e8bb858242665/]

And the getItemDataCallback callback method is used as the second parameter:

[crayon-5f8fbbe18e8cf207504107/]

In the above callback we grab the ChangeKey from the GetItem result and construct a list of email addresses (in case you are forwarding to several addresses) to be used as an XML fragment that we’ll inject into another method to return the full XML syntax for a final Mailbox.makeEwsRequestAsync method that we need to call.  In this case, the CreateItem method (yes – it is not “ForwardItem”):

[crayon-5f8fbbe18e8dd115623515/]

Note the MessageDisposition attribute for the CreateItem element.  We’re using ‘SendAndSaveCopy’, but you can use ‘SaveOnly’ if you want to save a draft and send the email manually later, or ‘SendOnly’ if you do not want to save a copy in the Sent Items folder.

You’ll also notice the ForwardItem element within the CreateItem element.  This is the area where we construct all the relevant values for the email that we are creating and forwarding – including the values for subject, recipients and body that we are grabbing from the input controls.  After this XML is sent on, we can examine the result in our callback:

[crayon-5f8fbbe18e8e9918607364/]

Everything should be good! We only need to check the content in the XML returned by the EWS call to ensure it worked:

2015-11-15_19-09-14

And of course we should also check the Mailbox where we forwarded the email to and ensure it was received – as per below!

2015-11-15_19-27-34

Enjoy, cheers and rock on!

SOURCE CODE AVAILABLE ON GITHUB

Eric Legault

Microsoft Outlook MVP (15 yrs). Author: Microsoft Office 2013 Pro Step By Step. Consultant/speaker/Outlook add-in builder/SharePoint pioneer. Guitarist: Maiden Canada (Iron Maiden tribute band)

You may also like...

%d bloggers like this: