Configuration

OAuth2 Application

Warning

This step needs to be done by the customer IT in Microsoft Entra or 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 Microsoft Entra and Google setups.

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.

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>/email/oauth, else https://localhost/email/oauth. Please note that http://127.0.0.1 isn't allowed.

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.

API Permissions

The email integration uses Microsoft's Delegated Permission model to request access to a mailbox based on a user consenting to the permission scopes detailed below. The user needs to be a member of the customer's domain and have access to the shared mailbox. See the Frequently Asked Questions for more information.

Click on the "Manage -> API permissions" menu link. Here you can set up the permissions the application requires. Click on the "Add a permission" button and add the following permissions (all found under Microsoft APIs -> Microsoft Graph -> Delegated permissions)

• User.Read (added by default)

  Required by the OAuth authentication flow to get user information.

• Imap.AccessAsUser.All

  Allow the email-integration to access the delegated mailbox.

• SMTP.Send

  Allow sending email from the delegated mailbox with OAuth authentication. This does not imply using Basic Authentication (see Frequently Asked Questions).

• offline_access

  Maintain access to the delegated mailbox independently of the login status of the authenticated user.

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

Client secret

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

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

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

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.

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

Find and enable "Gmail API" for the project.

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.

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

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 https://localhost.
• Authorized redirect URIs: same as URI above, but with /email/oauth attached, e.g. https://localhost/email/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. /email/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.

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 Microsoft Entra or 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.

Microsoft Entra Shared Mailbox

Warning

This step is only necessary for Microsoft Entra setups and needs to be done by an IT administrator 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 Microsoft 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.

• 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 Microsoft 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.

1. Add additional filters.
2. Add additional Info Tiles.
3. Update existing view configs.
4. Configure OAuth2 applications.
5. Configure templates.
6. Configure accounts.
7. 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_addresses_mailto	Followers' email addresses, mailto links
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: "<local-base-url-with-app-name>" # For example: http://localhost:5442/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

EmailEngine Access Token

Info

3018 is the default port that can be altered during limecrm-server installation.

1. Head into the graphical user interface for EmailEngine at <email-engine-base-url>. By default you can find the interface at http://127.00.1:3018/ on the server.
2. Navigate to "Access Tokens" in the left panel menu.
3. Click the "Create new" button to generate a new access token.
4. Enter a suitable description and allow only API scope.
5. Generate the token and copy it.

6. 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>"
   

7. Restart the web server and the task handler.

EmailEngine License

In order to use the email integration, you need to have a valid license for EmailEngine. If you don't have one, please contact limepkg-email maintainers for more information.

To register the license, go to http://127.0.0.1:3018/admin/config/license and register the license key.

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.