​
Authorization Type

Carbon uses OAuth 2.0 to connect to Outlook.

​
Authorization Flow

Log into your Microsoft account.

After your account is authenticated, you will be directed to the following screen. Now your emails can be synced.

​
Custom OAuth Credentials

Custom OAuth credentials is only required for customers who enable white labeling.

​
Setting up the OAuth App

  1. Create or log into your Microsoft Azure Account.

  2. Under Azure Services, select App Registration -> New registration.

  1. Select Accounts in any organizational directory (Any Microsoft Entra ID tenant - Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox) as the Supported account types.

  1. Add https://api.carbon.ai/integrations/outlook as the Redirect URI and select Web under the Select a platform dropdown. You can also opt to use a custom CNAME record pointing to https://api.carbon.ai. The domain path must still be /integrations/outlook.

  1. Under Manage -> API permissions add the permissions Mail.Read, offline_access, openid, and User.Read.

  1. Under Client credentials, click Add a certificate or secret -> New Client Secret. Then copy the client secret’s Value and share it with us via Slack.

  1. Navigate to the Overview tab then copy the Application (client) ID and share it with us via Slack.

  1. Customize your app branding under Manage -> Branding & properties.

​
Synchronization

After successfully connecting your Outlook account, you have the flexibility to choose which emails to sync using the filters and folder parameters via the integrations/outlook/sync endpoint.

​
Filters Parameter

The filters parameter is a JSON object with key-value pairs, supporting AND and OR operations.

Below are the supported filter keys:

​
category

Custom categories created in Outlook.

​
after

Accepts a date in the format YYYY/mm/dd (e.g., 2023/12/31), enabling the retrieval of emails after a specified date.

​
before

Accepts a date in the format YYYY/mm/dd (e.g., 2023/12/31), enabling the retrieval of emails before a specified date.

​
from

Supports an email (email@address.com) as a string from which the email was sent.

​
has

Supports the value attachment as a string to filter for all emails sent from an account.

Here are some examples:

{
    "filters": {
        "key": "category",
        "value": "Test"
    }
}

{
    "filters": {
        "key": "after",
        "value": "2024/01/07"
    }
}

​
Folder Parameter

The folder parameter allows you to specify the folder from which to sync emails. By default, emails are retrieved from the inbox folder. To specify a custom folder, include it in the query:

{
    "folder": "Folder Name",
    "filters": {
        "key": "category",
        "value": "Test"
    }
}

​
Combining Filters and Operations

You can use AND and OR operations for more complex queries. Here’s an example:

{
    "filters": {
        "AND": [
            {
                "key": "after",
                "value": "2024/01/07"
            },
            {
                "OR": [
                    {
                        "key": "category",
                        "value": "Personal"
                    },
                    {
                        "key": "category",
                        "value": "Test"
                    }
                ]
            }
        ]
    }
}

You can use the resync_file API endpoint to programmatically resync specific Outlook emails. To delete specific emails from Carbon, you can use the delete_files endpoint directly.

To sync Outlook emails on a 24-hour schedule (more frequent schedules available upon request), you can use the /update_users endpoint. This endpoint allows organizations to customize syncing settings according to their requirements, with the option to enable syncing for all data sources using the string ‘ALL’. It’s important to note that each request supports up to 100 customer IDs.

Here’s an example illustrating how to automatically enable syncing for updated Outlook content for specified users:

{
    "customer_ids": ["team@carbon.ai", "sam@openai.com"],
    "auto_sync_enabled_sources": ["OUTLOOK"]
}

​
Microsoft Admin Approval

To allow Carbon to access your Microsoft applications (OneDrive and SharePoints), users might need to request admin consent approval.

Here’s a step-by-step guide:

​
Prerequisites

Before you begin, ensure you have:

  • Gone through Carbon’s managed OAuth flow and submitted the admin consent request (see screenshot below):
  • An administrator role or designated reviewer role to review admin consent requests

​
Approve the Request

  1. Sign in to the Microsoft Entra admin center as at least a Cloud Application Administrator who is a designated reviewer.

  2. Navigate to Identity > Applications > Enterprise applications.

  3. Under Activity, select Admin consent requests.

  4. Select the My Pending tab to view and act on the pending requests.

  5. From the list, select the Carbon application that is being requested.

  6. Review the request details:

    • Select Review permissions and consent to see what permissions are being requested by Carbon.
    • Select the App details tab to view the application details.
    • Select the Requested by tab to see who is requesting access and why.

  7. Approve the request to grant admin consent to allow Carbon to access your Microsoft application. All requestors will be notified that their request for access is granted. This allows all users in your tenant to access Carbon unless otherwise restricted with user assignment.

Do You Have the Right Permissions?

If you are unable to consent to the approval request under My Pending because the admin consent flow has not been activated, then you will need Global Administrator permissions. Once you are a Global Administrator, you can set up the admin consent flow or consent directly via Carbon’s managed OAuth flow.

GmailSlack