Outlook addins

Integrate Outlook with third-party services using add-ins built on JavaScript/HTML, enabling seamless access to emails, meetings, and more.

Outlook add-ins (and Office add-ins in general) are integrations built by third parties into Outlook by using Microsoft's web-based platform. Outlook add-ins are essentially JavaScript/HTML code that runs in the context of a browser in a sandbox with special access to Outlook items like email messages, meeting requests, responses and cancellations, and appointments.

Most Outlook add-ins are built to provide convenient integrations to a third-party system or service right from Outlook, like Customer Relationship Management, Customer Service, and Project Management,... and the add-in developers all end up developing the same or similar elements of their app:

• Provision a backend API that will support the client code.

• Implement user management (login/logout/session) which needs to be correlated with an authenticated Outlook user.

• Support one or more 3rd party authorization flows. For example, a user needs to link his or her CRM account, maybe also a cloud file storage.

• Proxy requests to 3rd party API's. Quite often direct API communications from JavaScript are blocked by CORS in browsers.

• Storing various add-in configurations for users or organizations.

• Offline mailbox access. Often special workers are implemented to run in the background when an add-in user is offline.

Aurinko aims to provide the necessary backend functionality for these add-ins so that developers could focus on the client code to create the best user experiences. Here are the steps to start using Aurinko as a backend API for your Outlook:

1. Get your developer API keys and put your app's client id into your client code or better pass it from your manifest file as a url parameter.

2. In most cases you want to have offline mailbox access or ability to access Graph API so provision your Azure app registrations.

3. After your add-in client code has initialized and gained access to Office JS API, test if the current user is already authenticated with Aurinko (logged in):

   curl -X GET -G https://api.aurinko.io/v1/user

   For a logged in user the request will return the user info and its active Aurinko accounts:

   {
       "id": "3df3ce21-07c0-4cec-a8de-ed4c570ee15c",
       "appId": 1,
       "email": "[email protected]",
       "authOrgId": "abcda5bb-1d9f-0514-a4c6-1234502167890",
       "trustedIdentity": true,
       "accounts": [
           {
               "id": 2739,
               "serviceType": "Office365",
               "type": "primary",
               "active": true,
               "daemon": false,
               "loginString": "[email protected]",
               "email": "[email protected]",
               "name": "Addin User",
               "authUserId": "abcdabcb-ad8d-4bee-bd69-787675478785",
               "authOrgId": "abcda5bb-1d9f-0514-a4c6-1234502167890",
               "authObtainedAt": "2021-03-21T16:58:56.823Z"
           }
       ]
   }

   Otherwise, 401 Unauthorized status will be returned in which case your addin needs to ask the user to login (see next step).

4. Office JS API provides a special idToken that can be used to validate a current user but we recommend using OAuth2 authorization flow to confirm the current user as this way your app can also get offline access to Graph API:

   curl -X GET -G https:/api.aurinko.io/v1/auth/authorize
       -d clientId='{APPLICATION_ID}'
       -d serviceType='Office365'
       -d scopes='Mail.Read Mail.Send'
       -d userAccount='primary'
       -d returnUrl='https://static.mydomain.com/outlook_auth_callback.html'

   The important parameter here is userAccount = primary which turns this account authorization into user session initialization (user login). Upon successful authentication and authorization the redirect to returnUrl will result in setting a session cookie which will allow your app to stay recognized by Aurinko until the user logs out.

   In addition to the login Aurinko gets access to Graph API with the following scopes: Mail.Read, Mail.Send. This will allow your app to work with the Outlook account while the user is not using your Outlook addin.

5. Authorize access to a 3rd party API. Contact us at [email protected] to arrange adding a connector for your system, i.e. {MyCRM}.

   curl -X GET -G https:/api.aurinko.io/v1/auth/authorize
       -d clientId='{APPLICATION_ID}'
       -d serviceType='{MyCRM}'
       -d userAccount='secondary'
       -d returnUrl='https://static.mydomain.com/outlook_auth_callback.html'

   Upon a successful authentication and authorization an Aurinko account representing your 3rd party API {MyCRM} will be added and your app can issue the following request again:

   curl -X GET -G https://api.aurinko.io/v1/user

   The request will return all Aurinko accounts associated with the current user session:

   {
       "id": "3df3ce21-07c0-4cec-a8de-ed4c570ee15c",
       "appId": 1,
       "email": "[email protected]",
       "authOrgId": "abcda5bb-1d9f-0514-a4c6-1234502167890",
       "trustedIdentity": true,
       "accounts": [
           {
               "id": 2739,
               "serviceType": "Office365",
               "type": "primary",
               "active": true,
               "daemon": false,
               "loginString": "[email protected]",
               "email": "[email protected]",
               "name": "Addin User",
               "authUserId": "abcdabcb-ad8d-4bee-bd69-787675478785",
               "authOrgId": "abcda5bb-1d9f-0514-a4c6-1234502167890",
               "authObtainedAt": "2021-03-21T16:58:56.823Z"
           },
           {
               "id": 2740,
               "serviceType": "{MyCRM}",
               "type": "secondary",
               "active": true,
               "daemon": false,
               "loginString": "[email protected]",
               "email": "[email protected]",
               "name": "Crm User",
               "serverUrl": "https://crm.repfabric.com",
               "authUserId": "374",
               "authOrgId": "999",
               "authObtainedAt": "2021-03-21T17:39:10.513Z"
           }
       ]
   }

6. Now your addin can access either Graph API (through Aurinko's unified API) or the 3rd party API. Specify an account id in the special header X-Aurinko-AccountId and use Aurinko Email/Calendar/Contact to access those accounts.

   curl -H 'X-Aurinko-AccountId: 2739'
       -X GET https:/api.aurinko.io/v1/email/messages  
   
   curl -H 'X-Aurinko-AccountId: 2740'
       -X GET https:/api.aurinko.io/v1/contacts