Getting attachments in a mail app

Mail apps can now use a new set of properties and methods in the JavaScript API for Office and Exchange Web Services callback tokens to get the attachments of a message or appointment in an Exchange mailbox.

A mail app can use the JavaScript API for Office to get metadata about attachments on the current message or appointment. The following are the new API members that support getting attachments:

• Item.attachments gets metadata of the attachments for the currently selected appointment or message. This metadata includes attachment ID, type and size, etc.
• Mailbox.ewsUrlgets the URL of the Exchange Web Services (EWS) endpoint for the current email account.

The mail app can also use the following method to get an EWS callback token and pass it along with other necessary data to backend server-side code or a third-party web service:

• Mailbox.getCallbackTokeyAsync gets a callback token for server-side processing.

Using the IDs of the attachments in question, the URL of the appropriate EWS endpoint, and the EWS callback token, the backend or third-party web service can then call the EWS GetAttachment operation to stream the actual attachments from Exchange Server.

The following figure shows the process of getting attachments in a mail app.

Figure 1. Getting attachments in a mail app

The following code example shows how the mail app client-side code can use the new API to get the necessary information, before calling the backend service or third-party service:

1. Checking for the support of the attachment API.*
2. Getting the URL for the appropriate EWS endpoint for the user's mailbox.
3. Getting the set of attachment IDs for the user-selected item.
4. Getting an EWS callback token.

* Accessing attachments is currently supported if the mail app runs on Outlook Web App. The user’s mailbox can be on Exchange Online or Exchange on-premises. The feature is not available if the mail app is running in Outlook.

 Office.initialize = function () {
    $(document).ready(
    function () {
        initApp();
    });
};

// Initialize the mail app.
function initApp() {
    var serviceRequest;

    // Make sure the attachments API is available.
    // Currently the API is available for mail apps running
    // on OWA, if the user's mailbox is on Exchange Online.
    if (Office.context.mailbox.item.attachments == undefined) {
        // Handle as appropriate for your app if
        // API is not available.
    }
    else if (Office.context.mailbox.item.attachments.length != 0) {
        // The selected item has attachments.
        // Initialize a request object.
        serviceRequest = new Object();
        serviceRequest.attachmentToken = "";
        serviceRequest.ewsUrl = Office.context.mailbox.ewsUrl;
        // Array of attachment ids.
        serviceRequest.attachmentIDs = new Array();
        clientGetAttachments(serviceRequest);
    }

}

function clientGetAttachments(serviceRequest) {
    // Get the attachment IDs for all the attachments
    // for the user-selected item.
    var item = Office.context.mailbox.item;
    for (i = 0; i < item.attachments.length; i++)
        serviceRequest.attachmentIDs.push(item.attachments[i].id);

    // Get EWS callback token.
    Office.context.mailbox.getCallbackTokenAsync(
    function (asyncResult) {
        if (asyncResult.status === "success") {
            // Cache the result from the server.
            serviceRequest.attachmentToken = asyncResult.value;
            // With callback token, attachment IDs and
            // EWS URL end point all ready, call backend 
            // service. Backend service will call EWS GetAttachment
            // operation to get the actual attachments.
            makeServiceRequest(serviceRequest);
            // Handle any errors from getting the attachments.
        }
        else {
            // Handle any errors with the callback token.
        }
    });
}

The makeServiceRequest() function calls the server-side code or third-party web service. For more details about calling a service and implementing a service that calls an EWS operation (GetAttachments in this case), see How to: Get attachments from an Exchange Online server.