Email Connector

Functionality Overview

Connected service of the type "Email" allows to sync the incoming content of the email account with module items in Encodify.

As the majority of the connected services in Encodify, configuration of the integration consists of:

1.  Creating a module with fields in Encodify where the incoming email messages will be synced to

2.  Creating and configuring of connected account and connected service

3.  Creating action

Configuration

Module Configuration

After creating a module for email synchronization, the following fields can be configured for synchronizing properties of the incoming email messages. Created fields will be mapped in connected service.

Connected Service Configuration

Enable Feature Flag

For the connected service of the type "Email" to be available in Site Configuration > Connections > Connected Services, feature flag needs to be enabled in webapp.yaml

encode:
 webapp:
   connections:
     list: 
       - type: EMAIL
         enabled-sites: '*'

Create and Configure Connected Service

Go to Site Configuration > Connections > Connected Services and click "Add Service" next to the "Email" connected service type.

Step 1

First step of the Email connected service configuration is configuration of the connected account. In case email connected service and account has been configured before, it will be available for selection in "Account" drop down.

Leave default selection "Create New" in the "Account" selectbox to create new account and fill in the following required fields:

Step 2

On step 2 it is necessary to select a module to be used for syncing messages to and map the Message Id field.

All other options are not required but also useful. Please refer to the table below for more information.

Step 3

On step 3, map the fields from the selected module to the email attributes.

Please, note the following while doing mapping:

• there are no required fields, but at least 1 field must be mapped, otherwise, validation will be triggerd preventing from saving a connected service

• "Attachment" attribute should be mapped to the multiple file field type, as single file fields are currently not supported for syncing attachments.

After completing mapping and clicking "Save", connected account will be validated and connected service created.

After creation, corresponding connected account will appear in the list of existing connected accounts and all standard CRUD(Create, Read, Update, Delete) operations for the connected service will be available.

Action Configuration

Final step in configuration of Email service integration is creation of actions. To create an action, follow the below described steps:

1. Go to the configuration of the module mapped in Email connected service, click "Actions" menu.

2. Click "Create Action" on the Actions toolbar.

3. In the new action configuration window, enter name for the action.

4. Select "Scheduled" in the "Event" selectbox.

5. Select "Sync with Connected Service" in the "Action" selectbox.

6. Select configued email connected service  in the "Connected Service" select box.

7. In the "Type of Schedule" section, configure interval for synchronization.

8. Save the action.

Synchronization

With the interval specified in action properties, the inbox will be scanned for the incoming messages and corresponding items or comments (if enabled in Proofing settings and Email Connector settings) will be created in the mapped module.

MessageID field stores unique identifier for each synced message to prevent duplicate synchronization. This means, that when configuring the connected service and mapping modules, the "1 module = 1 account" rule should be followed. 

Message sync depending on selected type

• POP3/POP3S - all messages in inbox will be syncronized with items and "delete" flag will be sent after syncing with Encodify.

Note!

Some mail services allows to specify starting from which point of time email messages should be synced and how should be treatd after having been synced.  

Example of GMAIL POP3 settings:

• IMAP - only unread messages will be synced and "Seen" flag will be sent after synchronization.

OAuth 2.0 Mechanism for Gmail and Outlook IMAP

Available in version 14.0.0

Google has announced via Less secure apps & your Google Account - Google Account Help that starting May 30, 2022, ​​they will no longer support third-party apps or devices which ask you to sign into your Google Account using only your username and password. Starting from version 14.0.0, Encodify will follow the recommended way to access mail from 3rd party providers OAuth 2.0 Mechanism  |  Gmail  |  Google Developers .

In order to configure email connected service using OAuth 2.0 mechanism, there are few additional steps that are required to generate OAuth2 Client ID and OAuth2 Client Secret keys in Developer Console. 

Below are the steps to generate keys in both Google Developer Console (Gmail) and in Azure Developer Console (Outlook).

Note: Follow Option 1 for Gmail and Option 2 for Outlook configuration.

Option 1: Gmail Configuration in Google Developer Console

Step 1

Open Google Developer Console and login with an existing Gmail account that will be used for the connected service configuration later on.

Step 2

Create a new or open an existing project from 'My Projects' dropdown:

Step 3

Navigate to Menu > Open API's and Services > Credentials

Step 4

Click '+CREATE CREDENTIALS' and select 'OAuth client ID'

Step 5

1. Select Application type: Web Application

2. Change the Name for the app (optional)

3. Click 'CREATE' button

Step 6

The Client ID and Client Secret has now been generated and can be downloaded to JSON format for later use.

Next step is to configure the Web App Connected Service using OAuth 2.0 mechanism. ( Skip below configuration for Outlook in case of configuring connected service for Gmail ).

Option 2: Outlook Configuration in Azure Developer Console

Step 1

Open Azure Developer Console and login with an existing Outlook account that will be used for the connected service configuration later on.

( In case of configuring Gmail, follow the steps in Option 1 above )

Step 2

1. Name the App

2. Selected 2nd Supported Account Type: "Accounts in any organizational directory (Any Azure AD directory - Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox)"

3. Click 'Register'

Step 3

Click Client Credentials > 'Add a certificate or secret' From the App page.

Step 4

Click '+ New client secret' from Certificates & Secrets page.

Step 5

From the pop-up window:

1. Add 'description' ( e.g. 'Client Secret')

2. Click 'Add' button

Step 6

The Client Secret has now been generated and should be copied from the Value field ( not Secret ID) for later use.

Note: This value will only be displayed once and will be hidden next time page is loaded. In the case value was not copied, the client secret can be deleted and new one should be created.

Step 7

The Client ID can be found from the Overview page:

Next step is to configure the Web App Connected Service using OAuth 2.0 mechanism.

Create and Configure Connected Service using Oauth 2.0 Mechanism

Go to Site Configuration > Connections > Connected Services and click "+ Add Service" next to the "Email" connected service type.

Step 1

First step of the Email connected service configuration using OAuth 2.0,  is configuration of the connected account. In case email connected service and account has been configured before, it will be available for selection in "Account" drop down.

Leave default selection "Create New" in the "Account" selectbox to create new account and fill in the following required fields and click 'Next'.

Note the differences for Gmail and Outlook configuration:

Step 2

1. Copy the 'Callback URL' from the service configuration page

2. Navigate to Google or Azure Developer Console

3. Add the 'Callback URL' to the list of Redirect URL's

Copy 'Callback URL'

Option 1: In Google Developer Console:

1. Navigate to API's and services > Credentials > OAuth 2.0 Client IDs > {Name}

2. Paste the Callback URL to 'Authorized redirect URLs'

3. Click SAVE

4. Return back to Encodify Web App > Site Configuration > Connections > Connected Services

Option 2: In Azure Developer Console:

1. Navigate to Overview > Add a Redirect URL

2. Click '+ Add Platform'

3. From Web applications select 'Web'

4. Paste Callback URL to Redirect URLs field

5. Click Configure 

6. Return back to Encodify Web App > Site Configuration > Connections > Connected Services

Step 3

1. Copy the 'Authorize URL' from the service configuration page

2. Open new tab in the same browser

3. Paste the authorize URL

4. Press Enter

5. Expected Response:

   {"result":"Auth code was successfully processed"}

Callback Authorized:

Troubleshooting:

NOT authorized: 401 Error message:

Solution: Make sure user is logged in to the WebApp in the same browser:

Step 4

Select a module to be used for syncing messages and map the Message Id field.

All other options are not required but also useful. More information in the beginning of this article.

1. Select 'Module'

2. Select 'Message id' field

3. Click NEXT

Step 5

Map the fields from the selected module to the email attributes.

After completing mapping and clicking "Save", connected account will be validated and connected service created.

After creation, corresponding connected account will appear in the list of existing connected accounts and all standard CRUD(Create, Read, Update, Delete) operations for the connected service will be available.

Step 6

Final step in configuration of Email service integration is creation of actions. For more details, please refer to the beginning of this article. (Actions Configuration ).

Known Behavior

• (Before version 9.106.0) For security reasons all the mark-up present in email body will be escaped.

• (Before version 9.106.0) Links to images in email body will not be parsed.

• During synchronization, all types of applicable validation for item creation (required, unique, field type) will take place. In case validation is triggered, synchronization will fail.

• Default values configured for fields will not be saved (e.g. Created date, Created by etc). 

• During saving body text to field - if field is RTE - html will be escaped.

• Comment creation with big size attachment (>10 MB) will lead to the failed synchronization (email will not be sent).

• Comment creation with restricted file format (like, exe) in attachments will lead to the failed synchronization (email will not be sent to some providers).

• All comments will generated an email when Encodify Inbox is configured for the module (agreed on demo 2.11.2022)

• Pasted media (files added via “Insert Media” option into Reply Email Template fields) cannot be rendered in received email

• Emoji cannot be shown in comment created from yahoo mail provider

• Yahoo, Outlook: Table properties, Font and Font Background colors from template are not applied in received message

• Comment with links send via mail in the end of ${CommentContent}

• Inline images are not inserted into comments as attachments or links

•  Behavior for POP3/IMAP is different:

  • POP3 - all messages will be downloaded, after processing messages will be deleted (the only supported Flag for POP3 - DELETED)

  • IMAP - only “Unseen” messages will be downloaded, after processing flag “Seen” will be set for them (search with criteria SEEN=false is used for filtering messages)