Implementing Custom Email Routing

The Symbee Connect Standard Email Channel provides the capability if needed, to finely control which queue inbound emails get delivered to using flexible email address criteria and keyword matching. The feature is referred to as Inbound Email Routing Rules.

The following information relates to providing a customized implementation for inbound Emails received through the Symbee Connect Standard Email Channel.

Refer to Standard Email Administration for details on configuring the Email channel and related Inbound Routing Rules in general, as well as the associated Email Channel Set Up step by step guide.

The Default Inbound Email Routing Rules Lambda

The default implementation for Symbee Connect Email Inbound Routing Rules is provided by a Rule Processing Lambda installed in your AWS Account as part of the Symbee Connect Email Channel CloudFormation.

The Lambda is invoked when an Email Configuration is configured to use an Inbound Routing Rule Set (see here for reference).

For each arriving email, the Lambda is invoked, supplied with the Inbound Rule Set configuration (the rules you configured within the Symbee Connect Administration Portal) and a reference to the inbound Email. The Lambda inspects the email, applies the configured rules appropriately, and returns the decided routing action (and target Skill Queue if appropriate) back to the Symbee Connect Email Channel gateway for routing.

Providing an alternative custom Email Routing Lambda

As an alternative to the default Rule Processing Lambda, you can provide your own custom Lambda implementation that receives the same inbound Routing Rule Set configuration (which you can optionally choose to refer to or not) and returns the decided routing action and Skill Queue, but uses your own custom logic to make the decision (for example, performing back-end CRM lookups, etc).

You can either develop your own Lambda from scratch, or copy the default Lambda code as a starting point and modify to suit (the default Rule Processing Lambda is intentionally deployed/provided as a small NodeJS based Lambda to allow you to optionally copy the code as a starting point).

Once you have your custom Lambda, configure the ARN of your Lambda in the Alternative Routing Lambda ARN field on your Inbound Routing Rule Set in the Symbee Connect Administration Portal - see here.

Pre-requisites and Requirements for using a Custom Email Routing Lambda

  1. Your custom Lambda needs to be in the same AWS region that the Symbee Connect Email CloudFormation stack was deployed in.

  2. The Standard Email Configuration configured in Symbee Connect needs to have a Default Skill Queue configured (the queue to send emails to if the Lambda invoke either fails, or does not return an alternative action or skill queue to use).

  3. The Inbound Rule Set configured in Symbee Connect (configured with your custom Lambda ARN) needs to have at least one Rule in the rule set.

    • All rules configured within your rule set in the Administration Portal are passed into your Lambda as arguments for use in your custom logic if needed
    • If your custom Lambda does not require any rule configuration, add one default rule of:
      • ToAddress: .* (Regular Expression, meaning "everything")
      • Match Action: ROUTE
      • Destination Queue: The same Skill Queue you configure as your Default Skill Queue on the Email Configuration

  4. The SymbeeManagementRole IAM Role in your AWS Account needs to have a policy added to it that allows your custom Lambda to be invoked (i.e. a policy that has an Allow of Action lambda:InvokeFunction on the ARN of your custom Lambda function). Perform these steps to do this:

    • Login into the AWS account, and navigate to IAM
    • Under Policies, click Create Policy (top right) to create a new policy
    • On the Specify Permissions page in the new policy, switch to JSON view, and replace the contents with the following JSON, replacing "the-arn-of-your-custom-email-rules-function" with the ARN of your Lambda function

    { "Version": "2012-10-17", "Statement": [ { "Sid": "AllowLambdaInvoke", "Effect": "Allow", "Action": "lambda:InvokeFunction", "Resource": "the-arn-of-your-custom-email-rules-function" } ] }

    • Click Next, give the Policy a Name (e.g. "CustomEmailRulesInvokePolicy") and Description, and Save.
    • Then under Roles, search for "SymbeeManagementRole" - you will find 1 IAM Role for each of your Symbee Connect Environments in the account. Click into the role for the respective Environment you are working with.
    • On the Permissions tab within the Role, at the top-right of that section, click Add Permissions => Attach Policies
    • Search for your new policy you created above, check it, and click Add Permissions on the bottom right.


Lastly, your custom Lambda needs to return a response object with the following properties on it - described below in JSON for reference. This result object is expected back by the Symbee Connect Email Channel gateway to complete the routing of the email:

{
    // 'success' - boolean: true or false. Return 'true' to route to the 'queueName' specified below.
    //             'false' results in the "Default Queue" on your Email Configuration being used.
    success: false,

    // 'queueName' - string: if 'success' (above) is true, the name of the Skill Queue to route to.
    queueName: null,

    // 'abandonEmail' - boolean: set to true to "STOP" the email from being sent anywhere. 
    abandonEmail: false
}