Configuration¶

OAuth2 Application¶

Warning

This step needs to be done by the customer Admin in Azure/ Google Cloud

In order to fetch any emails from a mail server you need to configure authentication between Lime CRM and the customer's mail server. This requires an OAuth2 application on the mail server, which the customer's IT will need to set up. The following sections show instructions for both Azure and Google setups.

Azure Enterprise/ Microsoft Entra Application Setup¶

These steps are specific for the email integration. If you need more information on the different options, check out Microsoft's guide.

New Application¶

Navigate to and log in to Azure Active Directory or Microsoft Entra admin center. You need to create an application that will manage the credentials, so open the "App registrations" page and hit the "New registration" button.

App registration

Fill out the form with the following information:

Call the application Lime CRM Email Integration.
For Supported Accounts Types, it depends on whether users are managed from one (single tenant) or several directories (multi tenant). Usually we use the Single tenant option.
For the Redirect URI choose Web as platform. The URI depends on the customer's setup:
- cloud customer: enter https://emailengine.internal-prod.limecrm.cloud/oauth
- on-prem customer: depends whether a valid HTTPS URL is provided for the "Lime CRM Email Integration" service. If so, enter <HTTPS URL TO SERVICE>/oauth, else http://localhost:<PORT>/oauth. Please note that http://127.0.0.1 isn't allowed. The port by default is 3000.

Info

When adding a new account to the email integration, the user will be asked to authenticate. Once they have consented, Microsoft will redirect the user to this redirect URL with appropriate tokens, so the creation of the account can be completed. /oauth is the name of the endpoint and can't be changed.

Application form

API permissions¶

Click on the "Manage -> API permissions" menu link. Here you can set up the permissions the application requires. By default, there's only "User.Read". Click on the "Add a permission" button and add the following permissions (all found under Microsoft APIs -> Microsoft Graph -> Delegated permissions)

Imap.AccessAsUser.All
SMTP.Send
offline_access

Afterward the API permission page should look like in this screenshot.

API permissions

Client secret¶

Click on the "Certificates & secrets" menu link and afterward the "New client secret" button.

Certificates and Secrets

Set a name for the new secret and choose an expiration time, we recommend 6 months. Once the credentials are created, you should see the actual secret value.

Warning

Make sure to copy this value (the one in the "Value" box) and store it safely, as it's not shown anymore once you close this page.

Warning

There is no built-in feature to remind you of the expiration date. Make sure to set a reminder in your calendar to renew the secret before it expires. More details can be found here.

Continue the configuration in Lime Admin. In that step you'll be asked for this secret as well as the Application (client) ID and the Directory (tenant) ID (both shown below).

Azure application

Google Client Application Setup¶

These steps are specific for the email integration. If you need more information on the different options, check out this guide.

New Project¶

Go to Google Cloud Console and click "Select a Project" in the top menu. Depending on if you have already created a project or not, the text might be different but the drop-down menu should be there. Click "New Project" and fill out the form:

Project name: Lime CRM Email Integration
Location: click Browse to display potential locations for your project. If you haven't created any parent organisation or folder, you can keep the default value "No organisation".

Application form

Click "Create" to finalize this step.

API permissions¶

It will take a while for the project to be created. After it's done, you can select it from the project menu.

Select Project

The newly created project will be empty and needs to be configured. To enable the required APIs, click on the top-left hamburger menu, find "APIs & Services," and select "Enabled APIs & Services."

Enabled APIs & Services

Find and enable "Gmail API" for the project.

Find Gmail API

Authentication¶

Click on the top-left hamburger menu, find "APIs & Services" and select "OAuth consent screen".

First you have to decide whether the app should be available to users within your organisation or to the public. Be beware, that making the app public means a months-long and very expensive security audit.

Info

Usually public access shouldn't be necessary and Internal is enough, but it depends on your organisation's setup in Google Cloud.
Next enter the project name from before as "App name" and provide an email address for your support and [email protected] as developer contact information.
On the next screen you select the required scopes. Unfortunately the exact scope can't be searched for. Instead add https://mail.google.com/ to the "Manually add scopes" section. This scope gives you access to IMAP, SMTP and the user's public profile.

Manually added scope

Add test users (only with public access): the application won't be immediately public, therefore you can add user accounts for a testing phase. During that time anyone who isn't listed won't be able to log in.

Credentials¶

Select "Credentials" on the left side menu. Click "Create Credentials" and pick the "Oauth client ID" option.

Google credentials

Fill in the following information:

Application type: Web application
URI:
- cloud customer: enter https://emailengine.internal-prod.limecrm.cloud/
- on-prem customer: depends on whether a valid HTTPS URL is provided for the "Lime CRM Email Integration" service. If so, enter <HTTPS URL TO SERVICE>, else http://localhost:<PORT>. The port by default is 3000.
Authorized redirect URIs: same as URI above, but with /oauth attached, e.g. http://localhost:<PORT>/oauth

Info

When adding a new account to the email integration, the user will be asked to authenticate. Once they have consented, Google will redirect the user to this redirect URL with appropriate tokens, so the creation of the account can be completed. /oauth is the name of the endpoint and can't be changed.

Hit the "Create" button and once back on the Credentials page check the "OAuth 2.0 Client IDs" section for the just created credentials. From there you can download or copy the credentials.

Info

This secret won't expire, but it's still a good idea to regularly rotate it. Make sure to set a reminder in your calendar to renew the secret ~ every 6 months. More details can be found here.

Google Client Secret

Continue the configuration in Lime Admin. In that step you'll be asked for the secret and the client ID (both shown above).

Secret Rotation¶

When rotating the client secret, create a new one (as described above) and update the secret on the corresponding OAuth2 application in Lime Admin. The old secret can be deleted from the Azure/ Google Cloud console. There is no action required regarding the accounts. The integration is immediately fully functional.

Info

We recommend rotating the secret every 6 months and to store it separately in a secure location.

Azure/ Entra Shared Mailbox¶

Warning

This step is only necessary for Azure/ Entra setups and needs to be done by an Admin of the customer.

We highly recommend to use shared mailboxes for the email integration. The following instructions include how to create a shared mailbox in Azure/ Entra. If you already have a shared mailbox, you can reuse that. Nevertheless, go through these steps to verify that the correct members are assigned.

Navigate to the shared mailboxes in your Microsoft 365 admin center.
Click "Add a shared mailbox", pick a name and email address for the mailbox and save the changes.

Shared mailbox

Next assign members to the mailbox. It's suggested as a next step. You can also find it later by opening the mailbox details and clicking "Edit" under Members.
Pick the members you want to have access to the mailbox. When the shared account is added to Lime CRM, the credentials to one of these members will be used to authenticate. Ideally, create a separate dedicated user in your Azure/ Entra application for this purpose.

Info

Ensure that only users with the necessary expertise have access to the mailbox. The email integration automatically marks emails as read when they are processed and moves them to a different folder in case of a failure. If a user manually interferes with this, by moving an email to a different folder for example, the email integration won't be able to process it.

Lime Admin¶

This is your checklist for the configuration part in Lime Admin.

Add additional filters.
Add additional Info Tiles.
Update existing view configs.
Configure OAuth2 applications.
Configure templates.
Configure accounts.
Configure runtime configuration.

Filters¶

Info

One of the filters (webclient.helpdesk.ticketswithunreadmessages) targets the helpdesk table. This assumes you have helpdesk as a conversation parent. If this is not the case, you need to manually open the downloaded file and remove the filter that targets the helpdesk table before you import the file. Alternatively, adjust the filter to desired behavior.

Info

If you are running Lime CRM in isolated cloud or on-premise, make sure that you have the package limepkg-filter-editor installed.

Use the Config Importer to import this file.

Info Tiles¶

Info

The following Info Tile config targets a filter (webclient.helpdesk.ticketswithunreadmessages) on the helpdesk table. If this filter was not imported in the previous step, skip this step.

Use the Config Importer to import this file.

Existing View Config¶

There is one field called earliestunread available on the conversation table that can be used to highlight that there are unread messages on your conversation parent (ticket, deal, etc.). To achieve this, add the following column to the table view config for your conversation parent:

{
    "property": "conversation.earliestunread",
    "title": "📫",
    "isDefault": true,
    "aggregated": true,
    "aggregate": {
        "operator": "MIN",
        "key": "min_earliestunread_0"
    },
    "component": {
        "name": "lwc-unread-message-icon-indicator",
        "props": {}
    }
}

Add Conversations as a Tab to your conversation parent (ticket, deal, etc.) for an overview of all conversations connected to a parent.
Add Conversation –> Conversation message to the Activities view on your conversation parent (ticket, deal, etc.) to include connected messages in the activity feed.
Add Following –> Following conversation messages –> Conversation message to the Activities view on your follower parent limetypes (coworker, person, company, etc.) to include connected messages in the activity feed.

OAuth2 Applications¶

You can manage your OAuth2 applications under the corresponding tab in the Email Integration settings in Lime Admin. Use the details you received when creating a new OAuth2 application in the OAuth2 application setup. Make sure to enter the same redirect URL as previously configured on the OAuth application. In case of the cloud customer that should be https://emailengine.internal-prod.limecrm.cloud/oauth.

You might need to "Sync applications & accounts" if your restored database had previously saved data for the email integration, e.g. by moving backup files between different environments. Otherwise, you can ignore the button. Check the help text next to the button or this section for more information.

Templates¶

Info

Only used for shared accounts.

You can manage your templates under the corresponding tab in the Email Integration settings in Lime Admin. The default template (provided by hitting the Use default template button) can be customized either by copying and pasting the template into Lime Marketing or by manually editing the HTML. For instance, you can modify the font throughout the entire template by updating the font-family attribute in the body class within the HTML code.

The following merge codes are supported in templates:

Merge code	Description
`conversation_update_info`	Information about what kind of update happened to a conversation you are in
`other_followers_info`	Information about who else the message was sent to
`reply_info`	Information about the reply options
`conversation_messages`	Content of the whole conversation thread
`followers`	Followers in the format "name (email address)", comma separated
`follower_addresses`	Followers' email addresses, comma separated
`follower_names`	Followers' names, comma separated
`num_followers`	Number of followers
`recipient_address`	Recipient's email address
`recipient_name`	Recipient's name
`sender_address`	Sender's email address
`sender_name`	Sender's name

Accounts¶

You can manage your accounts under the corresponding tab in the Email Integration settings in Lime Admin.

Shared Accounts¶

Warning

The first step is to make sure that no unwanted emails are still in the inbox folder of the shared accounts you want to add to this integration. Every unseen (i.e. new) email in the inbox folder will be imported to Lime CRM.

When you add a shared account, enter a suitable display name, since the name will appear in emails sent from this account.

For Outlook OAuth2 applications: Enter the email address of the shared account in the email field. When you proceed to authenticate, apply user credentials for a user who has been granted access to the shared account. You can find more details on Azure/ Entra accounts here.
For Gmail Oauth2 applications: Enter the email address of the shared account in the email field. When you proceed to authenticate, use the same shared account.

Runtime Configuration¶

The standard runtime configuration can be found at the root level in the Email Integration settings.

Conversation Parent Limetypes¶

Info

Only used for shared accounts.

Configure the main object to which the email conversation will be attached. This configuration will be set up for each account individually. For instance, you can configure the [email protected] account to create "Tickets" for all its conversations, or set the [email protected] account to create "Deals". It is also possible to create multiple conversation parents for the same account.

Example Configuration¶

{
    "personalizedEmails": true,
    "conversationParents": [
        {
            "relationConversation": "conversation",
            "accounts": ["<account_id>"],
            "properties": [
                {
                    "property": "subject",
                    "messageProperty": "subject"
                },
                {
                    "property": "description",
                    "messageProperty": "plainText"
                },
                {
                    "property": "person",
                    "messageProperty": "fromAddress",
                    "searchPath": "person.email"
                },
                {
                    "property": "company",
                    "searchPath": "person.company"
                },
                {
                    "property": "email",
                    "messageProperty": "fromAddress"
                },
                {
                    "property": "source",
                    "default": "email"
                },
                {
                    "property": "phone",
                    "searchPath": "person.mobilephone"
                }
            ],
            "limetype": "helpdesk",
            "relationDocument": "document"
        }
    ],
    "followerParents": [
        {
            "propertyAddress": "email",
            "propertyName": "name",
            "relationFollower": "follower",
            "limetype": "person"
        },
        {
            "propertyAddress": "email",
            "propertyName": "name",
            "relationFollower": "follower",
            "limetype": "coworker"
        }
    ],
    "conversation": {
        "limetype": "conversation",
        "propertyThreadId": "threadid",
        "propertyReplyToId": "replytoid",
        "propertyEarliestUnread": "earliestunread",
        "propertySubject": "subject",
        "propertyAddress": "email",
        "propertyFirstMessageDate": "firstmessagedate",
        "propertyLanguage": "language",
        "propertySource": "source",
        "sourceOption": "email"
    },
    "conversationMessage": {
        "limetype": "conversationmessage",
        "propertyMessage": "message",
        "propertyEmailEngineId": "emailengineid",
        "propertyUniqueId": "uniqueid",
        "propertyEmailId": "emailid",
        "propertyDate": "date",
        "propertySource": "source",
        "relationConversation": "conversation"
    },
    "follower": {
        "limetype": "follower",
        "propertyName": "name",
        "propertyAddress": "email",
        "propertyParticipationLevel": "participationlevel",
        "propertyActive": "active",
        "propertySubscribed": "subscribed",
        "relationConversation": "conversation",
        "relationConversationMessage": "conversationmessage"
    },
    "messageFollower": {
        "limetype": "messagefollower",
        "propertyParticipationLevel": "participationlevel",
        "propertyMessageId": "messageid",
        "propertyQueueId": "queueid",
        "relationFollower": "follower",
        "relationConversationMessage": "conversationmessage"
    },
    "document": {
        "limetype": "document",
        "propertyComment": "comment",
        "propertyType": "type",
        "documentType": "other",
        "propertyDocument": "document",
        "relationConversationMessage": "conversationmessage"
    },
    "embeddedFile": {
        "limetype": "embeddedfile",
        "propertyDocument": "document",
        "relationConversationMessage": "conversationmessage"
    }
}

Application Configuration¶

The email integration is using the application configuration in order to configure the base url for EmailEngine webhook delivery attempts.

There are also possibilities to override default server side configuration through the application configuration.

Windows On-Premise Installations¶

For Windows on-premise installations, the application level configuration is expressed in the file %ProgramData%\Lundalogik\LIME Pro Server\application_config.yaml. If it does not already exist, just create it.

Add the following:

<application-display-name>:
  config:
    limepkg_email:
      webhook_base_url: "<public-base-url-with-app-name>" # For example: https://addons.lime-crm.com/addons/

Restart the web server and the task handler.

Cloud Installations¶

For Cloud installations, the application configuration is configured in Cloud Admin.

Add following to the Configuration box for your application in Cloud Admin:

{
    "limepkg_email": {
        "webhook_base_url": "<public-base-url-with-app-name>" // For example: https://addons.lime-crm.com/addons/
    }
}

Optional Application Configuration¶

There are possibilities to tailor email integration to meet customer needs with the following config. Note that the following config is completely optional. If not configured, default values are automatically used.

Key	Default	Description
`config.limepkg_email.handle_unprocessed_emails_enabled`	True	Enable automatic recovery process.
`config.limepkg_email.vacuum_cleaner_grace_period`	2	Skip messages in recovery process that are newer than X minutes.
`config.limepkg_email.max_import_age_for_failed_messages`	1	Recover failed messages that are newer than X days.
`config.limepkg_email.attachment_max_size_mb`	25	Do not import messages that exceeds maximum attachment limit X MB.
`config.limepkg_email.incoming_message_webhook_task`	`limepkg_email.tasks.tasks.message_to_limeobjects`	Use a custom task to handle the webhook of incoming messages.

Example configuration for on-premise:

<application-display-name>:
  config:
    limepkg_email:
      handle_unprocessed_emails_enabled: True
      vacuum_cleaner_grace_period: 2
      max_import_age_for_failed_messages: 1
      attachment_max_size_mb: 25

Example configuration for cloud, in Configuration box:

{
    "limepkg_email": {
        "handle_unprocessed_emails_enabled": true,
        "vacuum_cleaner_grace_period": 2,
        "max_import_age_for_failed_messages": 1,
        "attachment_max_size_mb": 25,
    }
}

Server Configuration¶

The email integration is using the server configuration in order to configure EmailEngine's API token and base URL, which are used to manage OAuth2 applications and accounts.

Windows On-Premise Installations¶

Head into the graphical user interface for EmailEngine at <email-engine-base-url>. By default you can find the interface at http://localhost:3000/ on the server.
Navigate to "Access Tokens" in the left panel menu.
Click the "Create new" button to generate a new access token.
Enter a suitable description and allow only API scope.
Generate the token and copy it.
Open the server config for the web server (%ProgramData%\Lundalogik\LIME Pro Server\Web Server\configs\config.yaml) and for the task handler (%ProgramData%\Lundalogik\LIME Pro Server\Task Handler\configs\config.yaml), and add the following in both files:
```
plugins:
  limepkg_email:
    email_engine:
      base_url: "<email-engine-base-url>"
      admin_token: "<token-generated-in-step-5>"
```
Restart the web server and the task handler.

Optional Server Configuration¶

You can also overwrite the default schedule, user and language for the recovery process. By default, it's set to run every 20 minutes. If you want to change this, add the following to the server config:

    plugins:
      limepkg_email:
        email_engine:
          handle_unprocessed_emails: 
            schedule: "<cron tab>" # Crontab generator: https://crontab.guru/
            username: "<username>"
            language: "<language>"

Cloud Installations¶

No action is required.