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;
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:
12345678910111213141516171819202122232425262728293031 <?xml version="1.0" encoding="UTF-8"?><!--Created:cb85b80c-f585-40ff-8bfc-12ff4d0e34a9--><OfficeApp xmlns="http://schemas.microsoft.com/office/appforoffice/1.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="MailApp"><Id>0437f8ab-69e5-4279-8df9-3cd6446cb055</Id><Version>22.214.171.124</Version><ProviderName>Eric Legault Consulting Inc.</ProviderName><DefaultLocale>en-US</DefaultLocale><DisplayName DefaultValue="ForwardAnEmail" /><Description DefaultValue="ForwardAnEmail"/><Hosts><Host Name="Mailbox" /></Hosts><Requirements><Sets><Set Name="MailBox" MinVersion="1.1" /></Sets></Requirements><FormSettings><Form xsi:type="ItemRead"><DesktopSettings><SourceLocation DefaultValue="~remoteAppUrl/AppRead/Home/Home.html"/><RequestedHeight>250</RequestedHeight></DesktopSettings></Form></FormSettings><Permissions>ReadWriteMailbox</Permissions><Rule xsi:type="RuleCollection" Mode="Or"><Rule xsi:type="ItemIs" ItemType="Message" FormType="Read" /></Rule><DisableEntityHighlighting>false</DisableEntityHighlighting></OfficeApp>
The UI will be simple, and provide some HTML controls to set some values in the email that we are forwarding:
So let’s do a quick code walkthrough!
Clicking the Forward button will fire the beginForwardAnEmail() function in AppRead/Home/Home.js:
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:
And the getItemDataCallback callback method is used as the second parameter:
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”):
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:
Everything should be good! We only need to check the content in the XML returned by the EWS call to ensure it worked:
And of course we should also check the Mailbox where we forwarded the email to and ensure it was received – as per below!
Enjoy, cheers and rock on!