​
Authorization Type

Carbon uses OAuth 2.0 to connect to Gmail.

​
Authorization Flow

After the user logs into their Gmail account, Carbon auto-syncs all emails based on the filters set via our API.

​
Configuration

​
Custom OAuth Credentials

Custom OAuth credentials is only required for customers who enable white labeling.
  1. Go to APIs and Services > Enabled APIs and Services in your Google Cloud console, then click on the button titled ENABLE APIS AND SERVICES and enable Gmail API.
  2. Then create an OAuth Client ID in the Credentials section under Gmail API. Select Web Application as the Application type and give it an identifiable name for your reference.

  1. Add https://api.carbon.ai as the Authorized JS origin and https://api.carbon.ai/integrations/gmail as an Authorized redirect URI. You can also opt to use a custom CNAME record pointing to https://api.carbon.ai for the Authorized JS Origin and Authorized redirect URI. However, for the Authorized redirect URI the domain paths must still be /integrations/gmail.

  1. Save the credentials. Download the credentials.json file once you save the OAuth Client ID data and share the file with Carbon.

  1. Configure your consent screen in the OAuth Consent Screen. Provide your App name, support email address, and brand logo. Add carbon.ai (or your custom CNAME) to Authorized domain.

  1. Click on Add or Remove Scopes button to add the following scopes: /auth/gmail.readonly

  1. If you wish to add test users, you can do so. These users will not see the “App is unverified” notification. Other users will see this alert.
  2. Click Publish App to make this app available to your end-users.

​
Synchronization

After successfully connecting your Gmail account, you gain the ability to selectively sync emails by utilizing the filters parameter via the /integrations/gmail/sync endpoint. This parameter operates as a JSON object comprising key-value pairs, supporting both AND and OR operations. Presently, our system accommodates a specific set of keys as detailed below:

​
label

Represents predefined Gmail labels such as “Important” or custom labels created by the user.

​
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.

​
is

Supports values like starred, important, snoozed, and unread to filter emails based on these attributes.

​
to

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

​
from

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

​
in

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

​
has

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

It’s crucial to adhere to the specified keys and values within the JSON object. Usage of keys or values outside this defined scope might result in unexpected behavior.

An example of a basic query with filters, which lists all emails that have the label Test:

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

You can use AND and OR operation as follows.

This setup ensures the retrieval of emails dated after January 7th that satisfy either of the two conditions: having the label “Personal” or being marked as ‘starred’. The structure allows for the effective use of AND and OR operations to filter emails based on the defined criteria.

This example demonstrates the highest level of nesting we support. You can’t add more AND/OR filters within the OR filter in the example below.
{
    "filters": {
        "AND": [
            {
                "key": "after",
                "value": "2024/01/07"
            },
            {
                "OR": [
                    {
                        "key": "label",
                        "value": "Personal"
                    },
                    {
                        "key": "is",
                        "value": "starred"
                    }
                ]
            }
        ]
    }
}

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

To sync Gmail files 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 Gmail content for specified users:

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