Generic Routed Email API

As an alternative to using Standard Email Configurations, Symbee Connect also supports servicing Email in your Contact Center that is routed from a CRM or custom in-house system. For custom systems, this API is used as the mechanism to send a request to route, queue, and deliver an Email that resides in your system, to agents signed into Symbee Connect. See Routed Email Configurations for further details.

Generic Routed Email API Endpoint

Routed Email requests are sent as HTTP POST requests, to the following API URL:

Where [global-region.] in the above URL is one of the following, depending on which region your Symbee Connect Environment resides:

• not supplied (defaults to us-east-1)
• us-west-2
• ca-central-1
• eu-west-2
• eu-central-1
• ap-southeast-1
• ap-southeast-2
• ap-northeast-1
• ap-northeast-2
• af-south-1

API Authentication

All POST requests to the API must have the following additional HTTP Headers present on the requests to succeed:

• X-sc-platform-code – static value of “AWS Connect”
• X-sc-company-code – Your Symbee Connect Company Alias
• X-sc-company-environment – Your Symbee Connect Environment name
• X-sc-secrets-region – Your Symbee Connect *AWS Secrets Manager Region* e.g. “us-east-1”
• X-sc-company-api-key – Your AWS Secrets Manager Symbee Connect API Key

Details on the 'X-sc-company-api-key' Header value

You will need to obtain your Symbee Connect API Key programmatically from AWS Secrets Manager.

When you sign up for Symbee Connect and decide to use any of the optional features that require running CloudFormations, the very first CloudFormation you run (see here for reference) installs an automatically rotating API Key into the AWS Account associated with the Symbee Connect Environment. This API key establishes a 2-way trust between you and Symbee Connect, and its value is required as a Header on all API requests.

To obtain the API key, use the AWS Secrets Manager API GetSecretValue action, passing in a SecretId of "SYMBEE_CONNECT_API_KEY". Use the value returned in the SecretString property of the response payload as the value to send in the 'X-sc-company-api-key'' header on Routed Email API requests.

Note that the SYMBEE_CONNECT_API_KEY value in Secrets Manager is regularly rotated, so it is best to not cache this value for an extended period of time (no longer than an hour).

API Request Payload

The Request POST payload is expected to be a valid JSON formatted payload. The payload is an array which can contain multiple requests. Each request is an object with the following parameters/properties:

Mandatory Request Object properties

platform

Value is a string. Use the static value of "AWS Connect".

companyCode

Value is a string. Use your Symbee Connect Company Alias.

environment

Value is a string. Use your Symbee Connect Environment name.

ownerId

Value is a string. An identifier indicating what Symbee Connect Routed Email Configuration to use to route the email task.

This value ultimately maps to a Symbee Connect Skill Queue that will route the Email. Each Routed Email Configuration in Symbee Connect has the CRM Owner ID its associated with. This allows you to logically indicate your own groupings for routings, and then map your “owner ids” to actual Symbee Connect Skill Queues in the Contact Center via each Routed Email configuration. Refer here for more discussion on this.

entityId

Value is a string. A unique identifier to associate with the Routed Email request. This value, along with any values provided in the optional attributes property below, will be available to all Symbee Connect CRM integration plugins for screen-pop setup upon delivery to an agent.

fromAddress

Value is a string. The original Email From Address (used only as a visual literal for display to the agent, and in reporting). Not used for queuing and routing.

toAddress

Value is a string. The original Email To Address (used only as a visual literal for display to the agent, and in reporting). Not used for queuing and routing.

subject

Value is a string. The Email subject line (used only as a visual literal for display to the agent)

attributes

Value is an Array of Objects. Optional additional attributes associated with the Routed Email request. Each object supplied in the array is a string key/value pair.

Optional/Custom Attributes

Up to 10 optional string/string key/value pairs can be supplied in the attributes array property above, with any name and value needed.

Attributes will be treated as “Task Attributes” and will be available in configuration to all Symbee Connect CRM integration plugins when setting up screen pops.

A maximum of 10 attributes can be provided.

Each Attribute key name must adhere to standard JSON property name requirements. The maximum name length is 255 characters.

Each Attribute value must be a string, and adhere to standard JSON string values. The maximum value length for a property value is 255 characters.

Request Payload Example

[
    {
        "platform": "AWS Connect",
        "companyCode": "abc-gadgets",
        "environment": "prod",
        "ownerId": "USPartsSpanish",
        "entityId": "e94c0a8a-0b69-11ec-9a03-0242ac130003"

        "fromAddress": "jtaylor@gmail.com", 
        "toAddress": "parts@gadgets.com",
        "subject": "Replacement part for Model X45T",

        "attributes" : [
            {
                "key": "CustomerId",
                "value" : "7762123-01"
            },
            {
                "key": "Class",
                "value" : "Commercial"
            }
        ]
    }
]

API Response Format

Standard HTTP Response Codes are used as responses. Therefore HTTP 4xx and 5xx response codes should be treated as failure.

An HTTP 200 OK response will return a payload containing a responseEnum and an errorMessage (for unsuccessful responses).

The responseEnum value will be set to either SUCCESS or ERROROCCURRED.

Example Response:

{
    "responseEnum": "SUCCESS",
    "errorMessage": null
}