Aurinko
Aurinko websiteAurinko blogAPI ReferenceContact Support
Aurinko API
Aurinko API
  • Getting started
    • What is Unified Mailbox API?
    • Getting started with Aurinko
    • Get your developer API keys
    • Adding Aurinko to Google Workspace allowlist
    • Bubble.io plugin
    • Team members and roles in applications
  • Unified APIs
    • Email API
    • Calendar API
    • Contacts API
    • Tasks API
    • Webhooks API
      • Configuring Pub/Sub for Gmail API Webhooks
    • Direct API
  • Authentication
    • OAuth Flow
      • Account OAuth Flow
      • User ОАuth Flow
      • Service Account OAuth Flow
    • Authentication scopes
    • Authorized return URLs
    • Google OAuth setup
    • Office 365 OAuth setup
    • ZOHO OAuth setup
    • Service accounts
      • Setting up G Suite service account
      • Setting up Office 365 daemon app registration
  • Scheduling
    • Create your first appointment booking page
    • Calendar Booking Page
    • Booking API
    • Group Booking API
  • Workspace Addons
    • Outlook addins
      • Create your first Outlook addin
      • Office 365: Installing Outlook addin
    • Microsoft Teams apps
      • Microsoft Teams bot setup
      • Create your first MS Teams app
      • Installing MS Teams app
    • Chrome Extensions with Google authentication
    • Google Workspace Add-Ons
  • Dynamic API
    • What is Dynamic (Virtual) API?
    • Getting Started with Dynamic API
Powered by GitBook
On this page
  1. Workspace Addons

Outlook addins

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

PreviousGroup Booking APINextCreate your first Outlook addin

Last updated 6 months ago

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": "user@yoxel.net",
        "authOrgId": "abcda5bb-1d9f-0514-a4c6-1234502167890",
        "trustedIdentity": true,
        "accounts": [
            {
                "id": 2739,
                "serviceType": "Office365",
                "type": "primary",
                "active": true,
                "daemon": false,
                "loginString": "user@yoxel.net",
                "email": "user@yoxel.net",
                "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 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": "user@yoxel.net",
        "authOrgId": "abcda5bb-1d9f-0514-a4c6-1234502167890",
        "trustedIdentity": true,
        "accounts": [
            {
                "id": 2739,
                "serviceType": "Office365",
                "type": "primary",
                "active": true,
                "daemon": false,
                "loginString": "user@yoxel.net",
                "email": "user@yoxel.net",
                "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": "user@yoxel.net",
                "email": "user@yoxel.net",
                "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
support@aurinko.io