Cordial Send

Cordial is a cross-channel marketing and data platform that collects customer data into one platform for use with audience segments, trends, and automated customer experiences.

Send a Cordial automation template to a single contact as soon as Amperity sees the customer interaction, using the automation templates send endpoint. Amperity sends one send request for each real-time point, for one contact. The request carries the attributes mapped on the Activate node as contact attributes, and its custom attributes as external variables.

The automation template is the target of this connector. To send email lists to Cordial on a schedule rather than in real time, use the Cordial destination.

This connector sends from a real-time journey. See Real-time destinations.

Requirements

1. The automation template must already exist in Cordial and be set up for API sends. See automation templates in the Cordial documentation. This connector sends a template; it does not create one.

2. A Cordial API key that allows the REST API methods listed under Credentials.

Credentials

This connector uses the “cordial” credential type, which has an API key and an API URL. You can reuse a “cordial” credential from the Cordial destination if its API key allows the methods listed below. A “cordial-aws” credential cannot be used with this connector.

Name and description

The name and description for a credential.

API key

Required. The API key for your Cordial account.

Amperity calls these Cordial REST API methods, relative to the API URL, so the API key must allow them:

POST /v2/automationtemplates/{key}/send
GET /v2/accountlists

Amperity calls GET /v2/accountlists only to test the connection when you save the destination. The test passes when Cordial answers with a success or with HTTP status 404, and fails on any other error, such as a rejected API key. It does not check that the key may send automation templates. When Cordial rejects a send because of the API key, the send fails and Amperity does not retry it.

API URL

Required. The API URL of your Cordial account. May be one of the following: https://api.cordial.io/, https://api.use1.cordial.io/, or https://api.usw2.cordial.io/.

Settings

Name and description

The name and description for a destination.

Business user access

By default a destination is available to all users who have permission to view personally identifiable information (PII).

Enable the Admin only checkbox to restrict access to only users assigned to the Datagrid Operator and Datagrid Administrator policies.

Enable the PII setting checkbox to allow limited access to PII for this destination.

Use the Restrict PII access policy option to prevent users from viewing data marked as PII anywhere in Amperity and from sending data to downstream workflows.

Contact identifier

Required. The identifier Amperity sends for the contact. May be one of the following:

• “email” sends “identifyBy” as “email”, with the value of the attribute named “email” as the contact’s email address. Each Activate node that sends to this destination must map an attribute named “email”, in lowercase, on its Attributes tab.

• “phone” sends “identifyBy” as “SMS”, with the value of the attribute named “phone” as the contact’s SMS channel address. Each Activate node that sends to this destination must map an attribute named “phone”, in lowercase, on its Attributes tab.

• “custom_key” sends “identifyBy” as “customKey”, with the value of the attribute named in Custom key name as the contact’s custom key.

Amperity does not change or validate identifier values, including phone numbers. Each value is sent exactly as mapped.

Custom key name

Required when Contact identifier is “custom_key”. The name of the custom key in your Cordial account. Amperity reads the contact’s key value from the mapped attribute that has this exact, case-sensitive name, so map an attribute with the same name on the Attributes tab of each Activate node.

The destination saves without this setting. The check runs on each Activate node that sends to the destination: its attributes show an error until Custom key name is set.

Include subscribe status

Disabled by default. When enabled and Contact identifier is “email” or “phone”, Amperity sends a “subscribeStatus” of “subscribed” for the contact’s email or SMS channel with every send, whether or not the contact already exists in Cordial. This setting has no effect when Contact identifier is “custom_key”.

Activate node settings

The rest of the configuration for this connector belongs to the journey that sends to it. Add this destination to an Activate node, then configure the following fields on that node. Two nodes may send to the same destination with different templates and custom attributes. Mapped attributes are set once for the destination in the journey, so every node that sends to it uses the same mapped attributes.

template-key

Required. On the Payload tab. The key of the Cordial automation template to send.

Attributes

Every attribute mapped on the Attributes tab is sent in the request’s “contact” object, using the name it is mapped to. Map each attribute to the name of the contact attribute key in Cordial. Unlike the Cordial destination, this connector does not change attribute names before sending them.

Attribute names on the Attributes tab may contain only letters, numbers, hyphens, and underscores, must be unique, and cannot be blank. Each node must have at least one attribute enabled. A Cordial contact attribute key that contains other characters, such as a dot, cannot be mapped.

Values are sent as mapped. Date values are sent as “YYYY-MM-DD” strings; datetime values are not converted to that format. An attribute that the customer’s profile has with no value (null) is sent as null. An attribute that the profile does not have, or an enriched or custom attribute with no value, is left out of the request. The contact identifier is always sent, as null when it has no value.

The attribute that holds the contact identifier is sent as described under Contact identifier, in place of an attribute with its own name.

Custom attributes

Attributes added on the Custom attributes tab are sent in the request’s “extVars” object, using their names. When a node has no custom attributes, the request has no “extVars” object.

Request body

For example, with Contact identifier set to “email”, Include subscribe status disabled, attributes mapped to “email” and “first_name”, and a custom attribute named “order_id”, Amperity sends:

{
  "identifyBy": "email",
  "to": {
    "contact": {
      "email": "customer@example.com",
      "first_name": "Ada"
    },
    "extVars": {
      "order_id": "123"
    }
  }
}

With Include subscribe status enabled, the email address moves into the email channel:

{
  "identifyBy": "email",
  "to": {
    "contact": {
      "channels": {
        "email": {
          "address": "customer@example.com",
          "subscribeStatus": "subscribed"
        }
      },
      "first_name": "Ada"
    },
    "extVars": {
      "order_id": "123"
    }
  }
}

Failed sends

Amperity makes up to three attempts at each send. Within an attempt, Amperity retries the request up to five times, with increasing waits, after a connection error, a request timeout (408), a rate limit error (429), or a server error (5xx). One send can therefore make up to 18 requests.

How Amperity handles each failure:

• 400, 401, or 403. The send fails without another attempt. Check the API key, the template-key, and the attributes mapped on the Activate node.

• 404 or 409. Amperity makes another attempt, up to three in all, without retrying within an attempt.

• Any other failure, including a timeout, connection error, 429, or server error that persists through the retries within an attempt, gets another attempt, up to three in all.

Amperity does not send a deduplication key with a Cordial send. Every retry and every attempt is a new, identical send request.

Amperity reports the send as successful when Cordial answers with any status below 400. Amperity does not read the response body, and does not check whether the message was sent.