Cordial FAQs

In this Article

Overview

Script Parameters

Introduction to Browser IDs

Cross-Domain Contact Identification

Identify

Event

Forget

Storing Parameters

Overview

The second iteration of the embedded JavaScript listener (JS listener) introduces a number of noteworthy enhancements.

Notable updates include the use of browser ID instead of contact ID for contact activity attribution; support for cross-domain contact identification and event tracking; inclusion of order and cart item calls into to the anonymous activities collection; and bundling of contact identify, create, and update operations into one call.

Additionally, several infrastructure enhancements were made resulting in significant improvements to the security and stability of the JS listener script.

Note: The Embedded JavaScript Listener v2 article covers installation instructions and provides script parameter use case examples.

Script Parameters

Although much of the core functionality remains unchanged, there are notable functional and structural differences between JS listener v1 and v2 script parameters. The following comparison table illustrates the differences.

Parameter

JS Listener V1

JS Listener V2

Description

identify

cordial.identify(pk|cid)

NA

Identify a contact.

contact

cordial.contact(data, options)

crdl('contact', auth_data, contact_data)

Identify, update or create a contact.

event

cordial.event('name', data)

crdl('event', 'action_name', data)

Send event, order and cart item calls to Cordial.

order

cordial.order(orderData)

crdl('order', order_data)

Send order data to the orders collection in Cordial.

cart

cordial.cart('clear')

crdl('cart', 'clear')

Clear cart contents.

cartitem

cordial.cartitem('action', data)

crdl('cartitem', 'action', cart_data)

Add, remove and track cart items.

forget

cordial.forget()

crdl('forget')

Clear current browsing session and assign a new browser ID.

connect

NA

crdl('connect', account_key, {config});

Configure account connection.

param store

t.setAttribute("data-cordial-source-keys", "utm_source");

crdl('param-store', 'utm_source')

Store URL strings as variables.

Introduction to Browser IDs

JS listener v2 introduces the use of browser IDs as a way of attributing and referencing contact activity. This is a departure from the previous version of the script, where the primary contact ID was used in a similar manner.

Browser ID is a randomly generated string that is assigned at the beginning of a browsing session. All contact activity thereafter is attributed to the browser ID for future reference. Once the contact becomes identified through signup, login or similar event, all browser ID attributed activity is copied into contact's profile.

Note: Browser ID is perishable and does not serve as the primary contact key.

If the contact is not immediately identified, their activity will be stored in the anonymous history collection. For contact identifications that take place at a later time, JS listener v2 will search the anonymous history collection using the initially assigned browser ID and copy matching activity to the now identified contact's profile.

Cross-Domain Contact Identification

JS listener v2 supports cross-domain contact identification and event tracking, a feature not supported in JS listener v1 without custom-built solutions. Unlike contact ID, browser ID is bound to the contact's browser and persists across multiple domain names, while the script continues attributing event, order, and cart activity to the same browser ID.

Whether the contact has been identified prior to being redirected to a different domain or is identified while at the redirected domain, the script will retain access to browser ID attributed activity, starting from the moment the browsing session began on a JS listener v2 enabled website.

This solves the previously reported issue where contacts' cart data did not always carry over from one domain to the next. The result is a more seamless browsing experience without interruptions to contacts' interaction with the brand.

Note: The above is true provided each visited domain contains the same JS listener v2 configuration snippet including the same Cordial account key, trackUrl, and conectURL.

Identify

Although cordial.identify() method is no longer used in JS listener v2, contact identification still takes place within the crdl(contact) method when the primary contact key value (email address for example) is passed as authentication data. The difference is that crdl(contact) discretely validates authentication data, giving JS listener v2 the opportunity to copy browser ID attributed activity to contact's profile.

The crdl(contact) has become a multi-function method that can handle calls to identify, create and update contact data.

Contact Creation

A new contact will be created when previously unrecorded authentication data is passed with crdl(contact). Assuming [email protected] is not an existing contact, the following example will create a new contact and the current session browser ID will be assigned to them:

var auth_data = {

email: '[email protected]'

}

var contact_data = {

'channels':{

'email': {

subscribeStatus:'subscribed'

}

},

'first_name': 'Joy',

'age': '32',

'platinum': true

};

crdl('contact', auth_data, contact_data);

If, on the other hand, [email protected] was identified as an existing contact, the above example would update Joy's profile without creating a new contact entry.

When no authentication data is passed, JS listener v2 will use the current session browser ID to search the anonymous history collection. In the event no existing records match the same browser ID, a new record will be added to the anonymous history collection. Should a match be found, the passed data will be used to update the existing anonymous history record.

Note: Because crdl(contact) is able to identify, update or create a contact, the use of "upsert" parameter is no longer necessary to distinguish between updating or adding a contact.

Event

JS listener v2 expands anonymous event data collection to now include event, order, and cart item calls. All anonymous event activity will be attributed to the session browser ID and stored in the anonymous history collection, where it will remain until the contact is identified, or 30 days have passed since the contact was last active.

Forget

Browser ID can be disassociated from the current browsing session by using the crdl(forget) method. This is the recommended way of handling user logout events.

A common scenario where this may be useful involves keeping browsing sessions and browser ID attributed activity between two users on the same computer separate from one another. When one user logs out, calling crdl(forget) will result in a new browser ID for use by the next user.

Expiring a cookie is another way to disassociate and refresh the browser ID after a desired period of time has passed. This can be accomplished by specifying cookie expiration time in days using the cookieLife parameter within the JS listener v2 base installation script. The default cookie life is set to 365 days.

cookieLife: 365

Note: Cookie expiration does not impact the collected anonymous event data, which is stored in the Cordial platform.

Storing Parameters

The crdl(param-store) method will store URL string values such as utm_source and utm_campaign for later retrieval as parameters. This serves as a way to identify sources of traffic and using collected data to report on purchase attributions, campaign effectiveness, and a variety of other analytics.

This method operates in the same manner as t.setAttribute(data-cordial-source-keys) does in JS listener v1. A notable difference is that JS listener v2 handles Crdl(param-store) as a method call whereas t.setAttribute is configured within the JS listener v1 base installation script.

Table of Contents

Installation

Overview

cordial.identify() - Identifying a contact

cordial.contact() - Updating a contact

cordial.event() - Tracking custom events

cordial.cartitem() - Tracking cart items

cordial.order() - Tracking orders & purchases

cordial.forget() - Clearing cookies (useful for a logout event)

Tracking Google AdWords, traffic source or other URL query string values

Installation

Include the following base script before the closing body tag of the page or site template:

<script>

(function () {

window.cordialLoaded = window.cordialLoaded || null;

var t = document.createElement('script');

var d = 'd.subdomain.yourbasedomain.com';

t.setAttribute("data-cordial-track-key", "$accountkey");

t.setAttribute("data-cordial-url", d);

t.setAttribute("data-base-domain", 'yourbasedomain.com');

t.setAttribute("data-auto-track", false);

t.src = '//'+d+'/track.js';

t.async = true;

t.onload = window.cordialLoaded;

document.body.appendChild(t);

})();

</script>

Script Attributes

* Required

Attribute

Description

Type

Default

* data-cordial-track-key

Replace $accountKey with the account key value for your account.

Read more

valid account key

none

* data-cordial-url

See domain below.

valid domain

none

* data-auto-track

When set to true, a pageView event is captured on each page load (impression).

boolean

false

data-base-domain

Your base domain where cookies will be stored. Necessary for allowing cookies to be shared across subdomains such as shop.yourbasedomain.com.

valid domain

none

* t.src

Absolute path of the track.js file

URL

https://track.cordial.io/track.js

t.async

When set to true, the script will load asynchronously and will not adversely affect your page load speed.

boolean

true

t.onload

Useful when t.async is true and initiating custom functions which must only be fired when the track.js file is completely loaded.

function name

none

t.setAttribute("data-cordial-source-keys", "$key");

If set, the track script will pull values out of the URL query string for any of the keys defined. Useful for source tracking.

Read more

Key name or an array of key names

none

Setting domain (d) for account

At the time of this writing, Cordial is in the process of moving clients to vanity domains. If you do not yet have a vanity domain, then the domain is track.cordial.io. If you do have a vanity domain, then the domain should be set to d.subdomain.yourbasedomain.com

Setting data-cordial-track-key with your account key

The account key value can be found in the application under your username (top right) -> Administration> Account Settings> Account Info panel, see the Account Key value. If this is not set, make a request via a support ticket or email your Client Success Manager, and a key will be configured promptly.

Setting the data-base-domain

In most instances, contacts will be identified upon visiting your base domain. In order to remain identified when moving from the base domain to a subdomain, such as shop.yourbasedomain.com, it is necessary to store cookies at the base domain level. This will allow cookies to be shared across subdomains branching from the base domain.

Note: Ensure your base domain is entered as a root domain, without the www. subdomain. Adding www. before your base domain will cause it to be treated as a subdomain, and cookies stored under this subdomain will not be accessible to other subdomains such as shop.yourbasedomain.com.

Overview - How it works

If a contact arrives on your site from a tracked link, a cookie will be set identifying the referring message ID and the session browser ID.

Note: This version of the JavaScript listener no longer relies on the contact ID when identifying contacts or attributing and referencing contact activities. A cookie containing the session browser ID (bID) is set instead. The use of bIDshas been introduced in v2 of the JavaScript listener and extended to this version due to added security enhancements. Please check out our JavaScript Listener v2 Features article for more details.

If the user has not arrived from a tracked link, the user can be identified from another method (Ex: site login, or sign up). You may set the identity of the user as a contact in the cookie using the cordial.identify method.

If there is no referring message or known contact identifier available, an anonymous ID will be assigned to the session user. All event activity (events captured via cordial.event() method will be tracked for 30 days and attributed to the anonymous ID. In the event that a contact identifier becomes available for the anonymous user, activity thereafter will be tracked and attributed to the known contact, and previously generated event activity (captured via cordial.event() method) from their anonymous session will be copied into their contact record.

Tip: Event activity belonging to anonymous users cannot be viewed in the Cordial platform until the user's record is created through identification.

Note: Due to data privacy compliance (i.e. GDPR ), certain functionality of adding and editing contacts via JavaScript requires explicit consent and additional setup. Please contact your Client Success Manager or submit a support request for more info.

Note: The manner in which track script stores and uses cookies may change from time to time, without notice, to accommodate changes to Cordial products and services, and in response to new technologies and industry practices.

Using t.onload

If the base script is set to load asynchronously, you will need to set a function name in the t.onload attribute and wrap any method calls in that function.

For Example:

function cordialLoaded() {

cordial.event('browse',{

"category": "shirts",

"product": "red t-shirt"

});

};

cordial.identify() - Identifying a contact

cordial.identify('[email protected]');

cordial.contact({});

The cordial.identify() method accepts either contactID or the primary key value (email address is the Cordial default primary key) for the contact.

Sets the contact identifier for the targeted user in the user's session cookie for use by any subsequent calls to update or track contacts.

This is useful for assigning a contact ID when the user is not referred through the system tracked link. Ex: After a login event where the contact ID becomes known.

cordial.contact() - Updating or creating a contact record

Once a contact is identified from a tracked link or the identify method, you may call cordial.contact() to add or update a contact record. You may also pass an object of attribute values, or list associations for a new or existing contact.

cordial.contact(contactObect,upsert)

cordial.contact({

'$attribute-key': 'value for attribute',

'$attribute-key': 'value for attribute',

'$list-key': true

},

{'upsert': false}

)

'Upsert' is an optional parameter, which if not specified, defaults to 'true' (both insert & update methods will apply). If set to 'false', a new contact record will not be created if one does not already exist (update only).

Simple example of updating or adding a contact:

cordial.contact({

'fname': 'Mark',

'age': 32,

'channels': {

'email': {

'address': '[email protected]',

'subscribeStatus': 'subscribed'

}

},

'platinum': true

})

The use of subscribeStatus key is situational and may not be necessary for all contact creation and update calls.

For example, if during the checkout process a new contact chooses not to receive promotional emails, it is not necessary to explicitly set their subscribe status to "unsubscribed", being that as a new contact without prior subscriptions, their subscribe status is initially set to "none". The best way to accomplish this is to leave the subscribeStatus key out of the call entirely.

If, however, the contact indicates by checking a box (or some other way) that they would like to receive promotional emails, the subscribeStatus key with the value of "subscribed" should be passed as demonstrated below.

var customer_data = {};

customer_data.channels = {};

customer_data.channels.email = {};

customer_data.channels.email.address = '[email protected]';

if(your_logic_for_box_checked){

customer_data.channels.email.subscribeStatus = 'subscribed';

}

cordial.contact(customer_data);

}

Simple example of updating a contact only if that contact already exists. Note: {'upsert': false} keeps a new contact record from being created and is treated only as an update to an existing contact.

cordial.contact({

'fname': 'Mark',

'age': 32,

'platinum': true

},

{'upsert': false}

)

Three examples of working with arrays.

cordial.contact({

'some_array': {'add': [apple]},

'second_array': {'remove': ['apple']},

'third_array': [apple, orange]

}

)

cordial.event() - Tracking Custom Events

Track an event by calling cordial.event with the event name and optional properties object.

cordial.event('eventName',propertiesObject)

Example:

cordial.event('browse',{

'category': 'skis',

'product': 'Rossignol Sin 7 SKIS 2015'

})

In the example above, a custom event called "browse" will be tracked and added to the contactactivities collection. A custom event may be named whatever you like, barring the following reserved event names.

Reserved event names

There are named events that are already tracked by the Cordial and those names should not be used for custom event tracking. The event names that should NOT be used for custom events:

click

open

message-sent

bounce

optout

All contactactivity records contain a timestamp and the contact ID of the user.

propertiesObject

You may also optionally pass an object of key/value pairs describing the event.

Note: Property keys consisting of numeric-only values (e.g. 57) or keys containing a "dot" (e.g. shoes.color) will be stripped.

Searching & Segmenting on custom events

These key/value pairs can be used for filtering the browse events. For example, an Audience Rule can be created to query all contacts who were tracked for a 'browse' event. Or, a filter can be added to the rule that queries all contacts who were tracked for a 'browse' event where the category is 'skis'.

cordial.cartitem() - Tracking Cart Items

Each contact has a Cart attribute associated with their profile. Calling cordial.cartitem() will add or remove items to a contact's cart. The productID is the primary key for the cart item. Adding items with the same productID will increment the quantity for that item versus add new item records.

Note: A user must first be in the Cordial Contacts Collection before adding cart information.

Request with a single cartitem

The add and remove actions support a single object ofcartitems.

cordial.cartitem('add',cartitemObject)

Example:

cordial.cartitem('add', {

'productID': '1234',

'sku':'1234-red',

'category':'shirts',

'name':'Red Shirt',

'images':['image1.jpg','image2.jpg'],

'description':'',

'qty': 1,

'itemPrice': 10.20,

'url':'',

'attr': {

'manufacturer': 'ExampleCo',

'size': 'L'

},

'properties': {

'custom_key': 'custom_value'

}

})

cordial.cartitem('remove', {

'productID': '1234'

})

Request with an array of cartitems

The add action supports an array of cartitems.

cordial.cartitem('add', [{

'productID': '1234',

'sku': '1234-red',

'category': 'shirts',

'name': 'Red Shirt',

'images': [],

'description': '',

'qty': 1,

'itemPrice': 10.20,

'url': '',

'attr': {

'manufacturer': 'ExampleCo',

'size': 'L'

}

}, {

'productID': '5678',

'sku': '5678-red',

'category': 'pants',

'name': 'Red Pants',

'images': [],

'description': '',

'qty': 1,

'itemPrice': 10.20,

'url': '',

'attr': {

'manufacturer': 'ExampleCo',

'size': 'L'

}

}])

Action

There are 2 possible actions: 'add' or 'remove'.

'add' - will add a new cart item record or increment the quantity of an existing record.

'remove' - will remove an existing cart item.

Cart Item Object

Key

Description

Type

Required

productID

Item Identifier

string

Required

sku

Item Number

string

Required

category

Item Category

string

Required

name

Item Name

string

Required

description

Item description

string

Optional

qty

Quantity in the cart

int

Optional

itemPrice

Price per item

float

Optional

url

Link to the item

string

Optional

images

image names or paths

array

Optional

attr

attribute value pairs

object

Optional

Cart Object

Below is an example of how the data is stored within a contact's profile. Note, the cartitem amount is automatically calculated (itemPrice x qty) and cart totalAmount is automatically calculated as the sum of all cart item amounts.

'cart': {

'totalAmount': 32.97,

'lm': '2015-10-22T20:43:38.373Z',

'cartitems': [

{

'productID': 'GreenPlaid123123',

'name': 'Green Plaid',

'sku': '111222333',

'category': 'Shirts',

'qty': 2,

'images':['image1,jpg','image2.jpg'],

'itemPrice': 10.99,

'amount': 21.98,

'description': 'Awesome shirt',

'url': 'http://www.shirts.com/GreenPlaid123123'

},

{

'productID': 'BluePlaid123123',

'name': 'Blue Plaid',

'sku': '111222444',

'category': 'Shirts',

'qty': 1,

'itemPrice': 10.99,

'amount': 10.99,

'description': 'Awesome shirt',

'url': 'http://www.shirts.com/BluePlaid123123'

}

]

}

Clearing a cart

To completely remove a cart object for a contact, use the cordial.clearcart() method. Ex: clearing a cart post-purchase.

cordial.clearcart()

cordial.order() - Tracking Purchases

Calling cordial.order() will update the order collection with a new record for the individual contact.

The add and remove actions support a single object oforder items.

cordial.order('add',orderObject)

cordial.order('add',{

'orderID': '',

'shippingAddress': {

'name': '',

'address': '',

'city': '',

'state': '',

'postalCode': 0,

'country': ''

},

'billingAddress': {

'name': '',

'address': '',

'city': '',

'state': '',

'postalCode': 0,

'country': ''

},

'items': [

{

'productID': '',

'sku': '',

'category': '',

'name': '',

'qty': 0,

'tags': ['tag1', 'tag2'],

'itemPrice': 0.0,

'salePrice': 0.0,

'url':'',

'attr': {

'color': '',

'size': ''

}

}

],

'tax': 0.0,

'shippingAndHandling': 0.0

})

Adding Order and Item Properties

The properties key can be used to insert additional custom order and item values. Values added using the properties key will become available for segmenting audiences using the Audience Builder (searching of nested order properties must be enabled in your account first). If having searchable order properties is a requirement for your account, please use the properties key in place of the attr key.

Example of adding order properties:

cordial.order('add', {

'orderID':'',

'items': [{

'productID': '',

'name': '',

'category': '',

'sku': '',

'tags': ['tag1', 'tag2']

}],

'properties': {

'order_discount': 1.00

}

})

Example of adding order item properties:

cordial.order('add', {

'orderID':'',

'items': [{

'productID': '',

'name': '',

'category': '',

'sku': '',

'tags': ['tag1', 'tag2'],

'properties': {

'brands': ['brand1', 'brand2']

}

}]

})

Action

There are 2 possible actions: 'add' or 'remove'

'add' - will add a new order record.

'remove' - will remove an existing order record

Order Object

Key

Description

Type

Example

Required

Order

orderID

Unique identifier assigned for the order

string

33451

Required

customerID

An ID value assigned by the ecommerce or CRM system

string

abc123

Optional

tax

The amount of the tax

float

22.50

Optional

shippingAndHandling

The amount charged for shipping and handling

float

0.0

Optional

shippingAddress

name, address, city, state, postalCode, country

object

see below

Optional

billingAddress

name, address, city, state, postalCode, country

object

see below

Optional

items

Each object describes an item of the order

array of objects

See parameters per item object below

Required

Parameters per each item object

productID

A unique identifier for the product.

string

1234abcd

Required

sku

The Stock Keeping Unit value for a particular item.

string

RF-WP33286-21

Required

category

The category given to the particular item.

string

Major Appliance

Required

name

The name of the product

string

S22-Refrigerator

Required

tags

Tags assigned to the item.

string

series-s2

Optional

qty

The quantity of this item purchased.

integer

1

Required

description

Description of the product

string

Great product!

Optional

url

Link to the product

string

http://myproduct.com

Optional

attr

Key value pairs describing attributes of the product. Values added cannot be searched using the Audience Builder or within Smarty for personalization.

object

"size":"large", "color":"red"

Optional

properties

Can be used in place of the attr key.Values added can be searched using the Audience Builder and within Smarty for personalization, ifsearching of nested order properties is enabled in the account.

object

"size":"large", "color":"red"

Optional

itemPrice

The item's retail price.

float

129.95

Optional

Optional parameters for billingAddress and shippingAddress objects

name

The name of the person or company making the order

string

Mark Smith

Optional

address

Defines the street address

string

13130 Silverlake Road

Optional

city

Defines the city

string

Hollywood

Optional

state

Defines the state

string

CA

Optional

postalCode

Defines the postal code

integer

90028

Optional

country

Defines the country

string

USA

Optional

Tracking Google AdWords, traffic source or other URL query string values

If t.setAttribute("data-cordial-source-keys", "$key"); is set, the track script will pull values out of the URL query string for any of the keys defined. The values will be stored in cookies and will be available to the Cordial track script as variables.

For example: If you were using an ad service to drive traffic, your URLs may look like:

http://mydomain.com?utm_source=google&utm_campaign=1234.

Telltheembedded script which URL query string parameters to listen for:

t.setAttribute("data-cordial-source-keys", "utm_source,utm_campaign");

The listener will now look for those query string keys and store their values in a cookie on your domain. The values are automatically available to you as variables. For example:

cordial.utm_source

cordial.utm_campaign

You can tell the script to listen for specificquery parameters, as long as the keys in the URL are alphanumerical. The keys may also contain: "-" and "_". Multiple keys should be comma separated.

You can use the variables in a number of ways, but a common use case would be to pass them as attribute values. The following example assumes an account with attributes called "source" and "campaign". When adding or updating a contact, you could pass the following variables.

cordial.contact({

"source":cordial.utm_source,

"campaign":cordial.utm_campaign

})

If the contact arrived at the page from the URL above, their profile would include the following:

"source": "google",

"campaign": "1234",

...

cordial.forget() - Clearing cookies (useful for a logout event)

Calling cordial.forget() will clear the cookies for a currently identified session.

cordial.forget()

array_diff

array_flip

array_intersect

array_keys

array_pop

array_push

array_reverse

array_search

array_splice

array_slice

array_splice

array_unique

array_unshift

array_values

asort

arsort

base64_encode

count

count_characters

current

date_format

default

emailObfuscate

empty

end

escape

explode

hash

in_array

intval

is_array

isset

json_decode

json_encode

jsonPrettyPrint

key_exists

next

nl2br

prev

print_r

rand

replace

regex_replace

round

sha1

sizeof

stopMessage

string_format

str_replace

strtotime

substr

time

trim

truncate

urldecode

urlencode

array_diff

Computes the difference of arrays.

array_diff($array1, $array2)

Type: Function

Example:

HTML & Smarty

Rendered Output

{$array1 = ["green", "red", "blue"]}

{$array2 = ["green", "yellow", "red"]}

{$diff = array_diff($array1, $array2)}

<pre>{json_encode($diff, 128)}</pre>

{

"2": "blue"

}

array_flip

Exchanges all keys with their associated values in an array.

array_flip($array)

Type: Function

Example:

HTML & Smarty

Rendered Output

{$fruits = ["d"=>"lemon","a"=>"orange","b"=>"banana","c"=>"apple"]}

{$tmp = array_flip($fruits)}

<pre>{json_encode($fruits, 128)}</pre>

{

"lemon": "d",

"orange": "a",

"banana": "b",

"apple": "c"

}

array_intersect

Computes the intersection of arrays.

array_intersect($array1, $array2)

Type: Function

Example:

HTML & Smarty

Rendered Output

{$array1 = ["green", "red", "blue"]}

{$array1 = ["green", "yellow", "red"]}

{$intersect = array_intersect($array1, $array2)}

<pre>{json_encode($intersect, 128)}</pre>

[

"green",

"red"

]

array_keys

Return all the keys or a subset of the keys of an array.

array_keys($array)

Type: Function

Example:

HTML & Smarty

Rendered Output

{$fruits = ["d"=>"lemon","a"=>"orange","b"=>"banana","c"=>"apple"]}

{$keys = array_keys($fruits)}

<pre>{json_encode($keys, 128)}</pre>

{

"d",

"a",

"b",

"c"

}

array_pop

Pop the element off the end of array.

array_pop($array)

Type: Function

Example:

HTML & Smarty

Rendered Output

{$colors = ['red','blue','green','purple']}

{$color = array_pop($colors)}

<pre>{json_encode($colors, 128)}</pre>

<pre>{$color}</pre>

[

"red",

"blue",

"green"

]

purple

array_push

Inserts one or more elements to the end of an array.

array_push($array,"value1","value2")

Type: Function

Example:

HTML & Smarty

Rendered Output

{$colors = ['red','blue','green','purple']}

{array_push($colors,"orange","yellow")}

<pre>{json_encode($colors, 128)}</pre>

[

"red",

"blue",

"green",

"purple",

"orange",

"yellow"

]

array_reverse

Return an array with elements in reverse order.

array_reverse($array)

Type: Function

Example:

HTML & Smarty

Rendered Output

{$fruits = ["d"=>"lemon","a"=>"orange","b"=>"banana","c"=>"apple"]}

{$fruits_reversed = array_reverse($fruits)}

{$utils->jsonPrettyPrint($fruits_reversed)}

{

"c": "apple",

"b": "banana",

"a": "orange",

"d": "lemon"

}

array_search

Searches the array for a given value and returns the first corresponding key if successful.

array_search('needle', $array)

Type: Function

Example:

HTML & Smarty

Rendered Output

{$colors = ['red','blue','green','purple']}

{$position = array_search('blue', $colors)}

<pre>{json_encode($colors, 128)}</pre>

<pre>{$position}</pre>

[

"red",

"blue",

"green",

"purple"

]

1

array_shift

Shift an element off the beginning of array.

array_shift($array)

Type: Function

Example:

HTML & Smarty

Rendered Output

{$colors = ['red','blue','green','purple']}

{$color = array_shift($colors)}

<pre>{json_encode($colors, 128)}</pre>

<pre>{$color}</pre>

[

"blue",

"green",

"purple"

]

red

array_splice

Remove a portion of the array and replace it with something else.

array_splice($array, offset)

Type: Function

Example:

HTML & Smarty

Rendered Output

{$colors = ['red','blue','green']}

{$color = array_splice($colors, 2)}

<pre>{json_encode($colors, 128)}</pre>

<pre>{$color}</pre>

[

"blue",

"green"

]

red

array_slice

Returns selected parts of an array.

array_slice($array,start,length,preserve)

Type: Function

Example:

HTML & Smarty

Rendered Output

{$colors = ['red','blue','green','purple']}

{$working_colors = array_slice($colors,1,2)}

<pre>{json_encode($working_colors, 128)}</pre>

[

"blue",

"green"

]

array_unshift

Prepend one or more elements to the beginning of an array.

array_unshift($array)

Type: Function

Example:

HTML & Smarty

Rendered Output

{$colors = ['red','blue','green','purple']}

{array_unshift($colors, "yellow")}

<pre>{json_encode($colors, 128)}</pre>

[

"yellow",

"red",

"blue",

"green",

"purple"

]

array_unique

Removes duplicate values from an array.

array_unique($array)

Type: Function

Example:

HTML & Smarty

Rendered Output

{$colors = ["d"=>"green","a"=>"green","b"=>"yellow","c"=>"blue"]}

{$tmp = array_unique($colors)}

<pre>{json_encode($colors, 128)}</pre>

{

"d": "green",

"b": "yellow",

"c": "blue"

}

array_values

Return all the values of an array.

array_values($array)

Type: Function

Example:

HTML & Smarty

Rendered Output

{$fruits = ["d"=>"lemon","a"=>"orange","b"=>"banana","c"=>"apple"]}

{$fruits = array_values($fruits)}

<pre>{json_encode($fruits, 128)}</pre>

{

"lemon",

"orange",

"banana",

"apple"

}

asort

Sort an array and maintain index association.

asort($array)

Type: Function

Example:

HTML & Smarty

Rendered Output

{$colors = ['red','blue','green','purple']}

{$tmp = asort($colors)}

{$colors = array_values($colors)}

<pre>{json_encode($colors, 128)}</pre>

{

"blue",

"green",

"purple",

"red"

}

arsort

Sort an array in reverse order and maintain index association.

arsort($array)

Type: Function

Example:

HTML & Smarty

Rendered Output

{$colors = ['red','blue','green','purple']}

{$tmp = arsort($colors)}

{$colors = array_values($colors)}

<pre>{json_encode($colors, 128)}</pre>

{

"red",

"purple",

"green",

"blue"

}

base64_encode

Encodes data with MIME base64.

Type: Modifier

Example:

HTML & Smarty

Rendered Output

{"foo"|base64_encode}

Zm9v

count

Counts the number of items in an array.

count($variable)

Type: Function or Modifier

Example:

HTML & Smarty

Rendered Output

{$colors = ['red','blue','green','purple']}

Function Syntax:<br>

The colors array contains {count($colors)} items.<br><br>

Modifier Syntax:<br>

The colors array contains {$colors|count} items.

Function Syntax:

The colors array contains 4 items.

Modifier Syntax:

The colors array contains 4 items.

count_characters

Counts the number of characters in a variable or text string. Use boolean parameter "true" to include whitespaces into the total count.

{$variableTitle|count_characters:true}

Type: Modifier

Example:

HTML & Smarty

Rendered Output

{$message.subject='Welcome! Here is Your Special Offer!'}

{$message.subject|count_characters}<br>

{$message.subject|count_characters:true}

31

36

current

Return the current element in an array.

current($array)

Type: Function

Example:

HTML & Smarty

Rendered Output

{$colors = ['red','blue','green','purple']}

{$working = current($colors)}

<pre>{json_encode($colors, 128)}</pre>

<pre>{$working}</pre>

[

"red",

"blue",

"green",

"purple"

]

red

date_format

Converts the date to a specified format.

http://php.net/manual/en/function.date.php

Type: Modifier

Example:

HTML & Smarty

Rendered Output

{$smarty.now|date_format}<br>

{$smarty.now|date_format:'\%D'}<br>

{$smarty.now|date_format:'\%A, \%B \%e, \%Y'}<br>

{$smarty.now|date_format:'\%Y-\%m-\%dT\%H:\%M:\%S'}<br>

{$smarty.now|date_format:'Y-m-d\TH:i:sO'}

Oct 9, 2017

10/09/17

Monday, October 9, 2017

2017-10-09T18:55:57

2017-10-09T18:55:57+0000

More date_format info and examples.

default

When smarty variable equals false (e.g. is an empty string) or has no value (i.e. null), allows you the opportunity to show default text.

Type: Modifier

Example:

HTML & Smarty

Rendered Output

{$coupon.code|default:'welcome10'}<br>

{$coupon.code='abc'}<br>

{$coupon.code|default:'welcome10'}<br>

welcome10

abc

emailObfuscate

Used to obfuscate an email address.

Type: Modifier

Example:

HTML & Smarty

Rendered Output

{$contact.channels.email.address|emailObfuscate}

j***n@g***m

empty

Checks to see if a value is empty.

empty($variable)

Type: Function

Example:

HTML & Smarty

Rendered Output

{$foo = 0}

{if empty($foo)}

Foo is empty

{else}

Value of foo is: {$foo}

{/if}

Foo is empty

end

Return the end element in an array.

end($array)

Type: Function

Example:

HTML & Smarty

Rendered Output

{$colors = ['red','blue','green','purple']}

{$working = end($colors)}

<pre>{json_encode($colors, 128)}</pre>

<pre>{$working}</pre>

[

"red",

"blue",

"green",

"purple"

]

purple

escape

Encodes or escapes a string or variable. Possible values are html,htmlall,url,urlpathinfo,quotes,hex,hexentity, javascript,mail. Default is html.

More escape info and examples.

Type: Modifier

Example:

HTML & Smarty

Rendered Output

{"http://example.com test"|escape:'url'}

http\%3A\%2F\%2Fexample.com\%20test

explode

Converts a string to an array based on a specified delimiter.

Type: Modifier

Example:

HTML & Smarty

Rendered Output

{$test = ","|explode:"a,b,c"}

{$test|print_r}

Array

(

[0] => a

[1] => b

[2] => c

)

1

in_array

Checks to see if an item exists in an array

in_array($needle, $haystack)

Type: Function

Example:

HTML & Smarty

Rendered Output

{$colors = ['red','blue','green','purple']}

{if in_array('red', $colors)}

Red is in the colors array.

{else}

Red is not in the colors array.

{/if}

Red is in the colors array.

More in_array info and examples.

intval

Get the integer value of a variable. Note, this will not round a number.

intval("value")

Type: Function

Example:

HTML & Smarty

Rendered Output

{intval("102.33")}<br>

{intval("102.63")}

102

102

is_array

Checks to see if an array exists.

is_array($variable)

Type: Function

Example:

HTML & Smarty

Rendered Output

{$colors = ['red','blue','green','purple']}

{if is_array($colors)}

Colors is an array.

{else}

Colors is not an array.

{/if}

Colors is an array.

isset

Checks to see if a value exists.

isset($variable)

Type: Function

Example:

HTML & Smarty

Data

Rendered Output

{if isset($contact.first_name)}

First name exists.

{else}

First name does not exist.

{/if}

"first_name": "Fred"

First name exists.

json_decode

Takes a JSON encoded string and converts it into a PHP variable.

json_decode($variable)

More info about json_decode.

Type: Function

Example:

HTML & Smarty

Rendered Output

{$enc = json_encode(["First"=>$contact.first_name,"Last"=>$contact.last_name,"Email"=>$contact.channels.email.address])}

enc: {$enc}

{$dec = json_decode($enc)}<br><br>

{foreach $dec as $key => $value}

{$key}: {$value}<br>

{/foreach}

enc: {"First":"Fred","Last":"Garvin","Email":"[email protected]"}

First: Fred

Last: Garvin

Email: [email protected]

json_encode

Returns a string containing the JSON representation of the suppliedvalue.

json_encode(["key"=>value,"key"=>value])

More info about json_encode.

Type: Function

Example:

HTML & Smarty

Rendered Output

{$enc = json_encode(["First"=>$contact.first_name,"Last"=>$contact.last_name,"Email"=>$contact.channels.email.address])}

enc: {$enc}

enc: {"First":"Fred","Last":"Garvin","Email":"[email protected]"}

jsonPrettyPrint

Prints data from a data collection in JSON format.

Type: Function

Example:

HTML & Smarty

Rendered Output

<H1>Debug contact</H1>

{$utils->jsonPrettyPrint($contact)}

Debug contact

{

"_id": "58d2fc99ac0c8117814d4e78",

"channels": {

"email": {

"address": "[email protected]",

"subscribeStatus": "subscribed",

"unsubscribedAt": ""

}

},

"last_name": "Fred",

"lastModified": "2017-10-03T00:11:14+0000",

"lists": [],

"createdAt": "2017-03-22T22:37:13+0000",

"lj": [],

"first_name": "Garvin",

"id": "58d2fc99ac0c8117814d4e78"

}

key_exists

Checks if the given key or index exists in the array.

key_exists('needle', $array)

Type: Function

Example:

HTML & Smarty

Rendered Output

{$fruits = ["d"=>"lemon","a"=>"orange","b"=>"banana","c"=>"apple"]}

{$check = key_exists('a', $fruits)}

<pre>{$check}</pre>

true

hash

Encode a string with a hashing algorithm.

Type: Modifier

Example:

HTML & Smarty

Rendered Output

{"test"|hash:"md5"}

098f6bcd4621d373cade4e832627b4f6

More info on hashing modifiers.

next

Return the next element in an array.

next($array)

Type: Function

Example:

HTML & Smarty

Rendered Output

{$colors = ['red','blue','green','purple']}

{$working = next($colors)}

<pre>{json_encode($colors, 128)}</pre>

<pre>{$working}</pre>

[

"red",

"blue",

"green",

"purple"

]

blue

nl2br

Converts"\n"line breaks to html<br />tags in the given variable.

Type: Modifier

Example:

HTML & Smarty

Rendered Output

{$articleTitle = "Sun or rain expected\ntoday, dark tonight"}

{nl2br($articleTitle)}

Sun or rain expected<br>

today, dark tonight

prev

Return the prev element in an array.

prev($array)

Type: Function

Example:

HTML & Smarty

Rendered Output

{$colors = ['red','blue','green','purple']}

{$working = next($colors)}

{$working = prev($colors)}

<pre>{json_encode($colors, 128)}</pre>

<pre>{$working}</pre>

[

"red",

"blue",

"green",

"purple"

]

red

print_r

Prints the contents of a data feed in a message.

Type: Modifier

Example:

HTML & Smarty

Rendered Output

<pre>

{$contact.cart.cartitems|print_r}

</pre>

Array

(

[0] => Array

(

[productID] => 1324

[sku] => 51515

[category] => Albums

[name] => David Hasselhoff

[qty] => 1

[itemPrice] => 9.99

[amount] => 9.99

[album] => Night Rocker

)

)

1

rand

A math equation that generates a random number between 2 specified numbers.

Type: function

Example:

HTML & Smarty

Rendered Output

{math equation='rand(1,1000)'}

127

Using the function to randomize content in a message.

replace

Replaces a character in a string with a specified character.

Type: Modifier

Example:

HTML & Smarty

Rendered Output

{$test = "hi there"}

{$test|replace:' ':'_'}

hi_there

regex_replace

Regular expression search and replace.

Type: Modifier

Example:

HTML & Smarty

Rendered Output

{$url_missing_http = 'website.com/path'}

{$new_url = $url_missing_http|regex_replace:"/^(website.com)/":"https://website.com"}

{$utils->jsonPrettyPrint($new_url)}

"https://website.com/path"

round

Rounds a number up or down.

Type: Modifier

Example:

HTML & Smarty

Rendered Output

{23.95|round}<br>

{23.23|round}

24

23

sha1

Encode a string with the sha1 hashing algorithm.

Type: Modifier

Example:

HTML & Smarty

Rendered Output

{"test"|hash:"sha1"}

a94a8fe5ccb19ba61c4c0873d391e987982fbbd3

More info on hashing modifiers.

sizeof

Counts the number of items in an array.

sizeof($variable)

Type: Function

Example:

HTML & Smarty

Rendered Output

{$colors = ['red','blue','green','purple']}

The colors array contains {sizeof($colors)} items.<br><br>

The colors array contains 4 items.

stopMessage

Stops a message from sending.

Example:

{if 'condition'}

{stopMessage}

{/if}

string_format

Formats a string. Use the syntax for sprintf() for the formatting.

Type: Modifier

Example:

HTML & Smarty

Rendered Output

{$number = 23.5787446}

{$number}<br>

{$number|string_format:"\%.2f"}<br>

{$number|string_format:"\%d"}

23.5787446

23.58

23

str_replace

Replaces a character in a string with a specified character.

Type: Function

Example:

HTML & Smarty

Rendered Output

{$test = "hi there"}

{str_replace(' ', '_', $test)}

hi_there

strtotime

Converts a date to a Unix timestamp, which is the number of seconds that have passed since 1970.

Type: Modifier

Example:

HTML & Smarty

Rendered Output

{"Oct 3, 2017"|strtotime}

1506988800

Example:

Rendering content based if today's date is between 2 dates.

{$jan01 = '2017-01-01 00:00:00'|strtotime}

{$dec31 = '2017-12-31 23:59:59'|strtotime}

{if $smarty.now >= $jan01 && $smarty.now <= $dec31}

Today is between Jan 01, 2017 and Dec 31, 2017

{else}

Today is NOT between Jan 01, 2017 and Dec 31, 2017

{/if}

substr

Returns a part of a string.

More info from W3schools

Type: Modifier

Example:

HTML & Smarty

Rendered Output

{"Hello world"|substr:0:1}

<br>

{"Hello world"|substr:6:5}

<br>

{"Hello world"|substr:3}

H

world

lo world

time

Returns the current time in the number of seconds since the Unix Epoch (January 1 1970 00:00:00 GMT).

Type: Modifier

Example:

HTML & Smarty

Rendered Output

{time()}<br>

{time()|date_format}

1507139097

Oct 4, 2017

trim

Removes whitespace and other predefined characters from both sides of a string.

More info from W3schools

Type: Modifier

Example:

HTML & Smarty

Rendered Output

{$foo = "Hello World"}

{$foo|trim:"Hed"}

llo Worl

truncate

This truncates a variable to a character length, the default is 80. As an optional second parameter, you can specify a string of text to display at the end if the variable was truncated. The characters in the string are included with the original truncation length. By default,truncatewill attempt to cut off at a word boundary. If you want to cut off at the exact character length, pass the optional third parameter ofTRUE.

More info on truncate from smarty.net.

Type: Modifier

Example:

HTML & Smarty

Rendered Output

{$articleTitle ='Two Sisters Reunite after Eighteen Years at Checkout Counter'}

{$articleTitle|truncate:30}<br>

{$articleTitle|truncate:30:"...":true}<br>

{$articleTitle|truncate:30:'...':true:true}<br>

Two Sisters Reunite after...

Two Sisters Reunite after E...

Two Sisters R...ckout Counter

urldecode

Decodes urlencoding in the given string. Plus symbols ('+') are decoded to a space character.

Type: Function

Example:

HTML & Smarty

Rendered Output

{$lnk = 'http\%3A\%2F\%2Fwww.cordial.com\%2Fproduct'}

{urldecode($lnk)}

http://www.cordial.com/product

urlencode

Encodes a URL string. Spaces are encoded as plus (+) signs.

Type: Function

Example:

HTML & Smarty

Rendered Output

{$lnk = 'http://www.cordial.com/product'}

{urlencode($lnk)}

http\%3A\%2F\%2Fwww.cordial.com\%2Fproduct

API Set Name: supplements

POST /supplements

GET /supplements

GET /supplements/{key}

PUT /supplements/{key}

DELETE /supplements/{key}

POST /supplements/{supplement}/imports

POST /supplements/{supplement}/records

GET /supplements/{supplement}/records

PUT /v2/supplements/{supplement}/clear

GET /supplements/{supplement}/records/{id}

PUT /supplements/{supplement}/records/{id}

DELETE /supplements/{supplement}/records/{id}

API Description and Functional Purpose

The supplements collection contains one or more supplemental data sets. Supplements extend the Cordial data model and support additional data related to your business. For example, a rental car company may have a supplement named cars that is meant to store records associated with each vehicle they operate. The cars supplement may have an arbitrary set of fields like vin, manufacturer, model, color, class, mileage, location, etc. to represent the attributes about vehicles. Each vehicle is then represented as a record with field/value pairs describing that vehicle's attribute details.

Additional information:

Supplements and fields may be added at any time to your database and are immediately available to all contacts once created.

Supplement IDs must be unique.

Supplement IDs cannot be 24 character hex strings. This format is reserved for system use.

Fields that will be used for search or audience building must be indexed. This is accomplished by including each field in the "indexed" array.

Indexed field names within a supplement must be unique. However, the same field name can be used within different supplements

Individual supplement record index values cannot exceed 1024 bytes.

Non-indexed fields can be entered as additional field value pairs in the JSON or as columns within an import file.

Indexed field definitions will enforce the type validations on record load and update. Non-indexed will not, nor will they undergo validation. This enables storing and maintaining wide latitudes of data both structured and unstructured.

Resource Associations

The following resource collections are associated to this collection.

Collection

Association

contacts

Supplements data can be associated back to a contact if the contactId is stored in a record.

POST /supplements

Method

URI Path

POST

/supplements

Creates a new supplement in the Cordial database using the appropriate JSON body.

Fields that will serve as search indexes need to be placed in the indexed array of fields. Additional non-indexed fields can be added in the JSON records, or by declaring the field as a column in an import file.

Posting more than one time for the same supplement key will generate an error.

Parameters

*Required

Parameter

Type

Description

Example

Supplement

*key

string

Unique identifier for a supplement.

cars

Indexes (array) -Individual supplement record index values cannot exceed 1024 bytes.

*field

string

The name of the field. Required to be unique within the context of this supplement only.

model

*type

string

Defines the field's data type. Options include: string, number, date, geo, or array.

string

Supplement

name

string

The name of the supplement

Cars

Example JSON Requests

The following will create a new supplement for cars with the indexed fields of model, year and mileage.

{

"key": "cars",

"name": "Cars",

"indexes": [{

"field": "model",

"type": "string"

},

{

"field": "year",

"type": "number"

},

{

"field": "mileage",

"type": "number"

}

]

}

Example Request URIs

The following URI in conjunction with the JSON will perform the POST.

http://<path>/supplements

GET /supplements

Method

URI Path

GET

/supplements

Retrieves all supplements from the Cordial database.

When retrieving a large amount of supplements in the response, it is possible to apply the per_page and page query string parameters to limit the count returned and page position.

Example Request URIs

Return all supplements

The following URI will retrieve all supplements and include all fields.

http://<path>/supplements

Return supplements filtered by page number and records per page

The following URI will retrieve all supplements starting from page 3grouping contacts by 10. For example, page 1 would have included the first 10, page 2 the second group of 10 and so on.

http://<path>/supplements?page=3&per_page=10

GET /supplements/{key}

Method

URI Path

GET

/supplements/{key}

Retrieves a supplement from the Cordial database.

The supplement is defined by the supplement's unique key value.

For example, /supplements/cars would return the response data for the supplement with the key of cars.

Example Request URIs

The following URI will retrieve the supplement with the key of cars, and include all fields.

http://<path>/supplements/cars

PUT /supplements{key}

Method

URI Path

PUT

/supplements

Updates a supplement in the Cordial database using the appropriate JSON body.

Parameters

Same requirements and schema asthe POST method above.

Example JSON Requests

The following will update the supplement for cars with the indexed fields of model, year, mileage, and upgrades.

{

"name": "Cars",

"indexes": [{

"field": "model",

"type": "string"

},

{

"field": "year",

"type": "number"

},

{

"field": "mileage",

"type": "number"

},

{

"field": "upgrades",

"type": "array"

}

]

}

Example Request URIs

The following URI in conjunction with the JSON will perform the POST.

http://<path>/supplements/cars

DELETE /supplements/{key}

Method

URI Path

DELETE

/supplements/{key}

Deletes a supplement from within the Cordial database.

The supplement is defined by the supplement's unique key value.

For example, /supplements/cars would delete the supplement with the key value of cars.

Example Request URIs

The following URI will delete the supplement with the key value of cars.

http://<path>/supplements/cars

POST /supplements/{supplement}/imports

Method

URI Path

POST

/supplements/{supplement}/imports

Creates a supplement data import job using the JSON body information.

The import file must contain an id field that uniquely identifies each record in a supplement. By default, existing supplements records are overwritten and new supplements are added.

Column headers can include one or more indexed fields along with any other optional non-indexed fields of your choosing.

If needed, an optional email confirmation can be set to trigger upon completion. This is helpful for larger imports.

Parameters

*Required

Source

Parameter

Type

Description

Example

*transport

string

Transport options include HTTP, FTP, SFTP or s3. Note that HTTP also incorporates HTTPS.

http

*url

string

URL or location of the import file.

http://files.example.com/123

server

string

Defines FTP or SFTP when using a file transport protocol (FTP) transport.

ftp

username

string

An account username for gaining access to the file location.

file-access-acct

password

string

The account password for the above user name.

Msm1th$99!

port

string

if transport = FTP or SFTP, and not using default

44

path

string

Options are FTP, SFTP and s3 only

ftp

aws_access_key_id

string

if transport = s3, public AWS id

asdf9g8asg89gd

aws_secret_access_key

string

if transport = s3, secret AWS key

dudhKDDHE476383kdsdhdkasK

aws_bucket

string

if transport = s3, AWS bucket name

some-bucket

aws_region

string

if transport = s3, AWS region

us-west-2

job

confirmEmail

string

Email address to send confirmation status message.

[email protected]

strategy

string

Options are insertOnly and updateOnly. If a strategy is not provided, by default records will be inserted and updated.

updateOnly

hasHeader

boolean

required, if columns is not included. Denotes the first row column headers are present, default is false.

true

nullMarker

string

Defines the value to use for ignoring or skipping attribute updates.

Upon import, if an attribute contains the nullMarker value (i.e. skip), then the attribute will be skipped or ignored.

skip

delimiter

string

Defines the data separation delimiter.

, - comma

: - colon

\t - tab

Example JSON Requests

The following will initiate an import job to load a CSV file with a header row from a secure HTTP location. A confirmation email will be sent the email address provided once the job is complete. The JSON response will provide a job id for checking job status if needed.

{

"source": {

"transport": "http",

"url": "https://files.example.com/new_data.csv"

},

"confirmEmail": "[email protected]",

"hasHeader": true

}

The following will initiate an import job to load a CSV file with a header row via a secure SFTP connection over port 22. It is configured to update existing data only. A confirmation email will be sent the email address provided once the job is complete. The JSON response will provide a job id for checking job status if needed.

{

"source": {

"transport": "sftp",

"server": "sftp.example.com",

"username": "myaccountid",

"password": "Msm1th$99!",

"port": 22,

"path": "/files/supp_data.csv"

},

"confirmEmail": "[email protected]",

"strategy": "updateOnly",

"hasHeader": true

}

The following will initiate an import job to load a CSV file with a header row via a secure s3 connection. It is configured to update existing data only. A confirmation email will be sent the email address provided once the job is complete. The JSON response will provide a job id for checking job status if needed.

{

"source": {

"transport": "s3",

"aws_access_key_id": "AAAAAAAAAAAAAAAAAAAA",

"aws_secret_access_key": "dudhKDDHE476383kdsdhdkasKDHDKDeiuealskjD",

"aws_bucket": "a-bucket",

"aws_region": "us-west-2",

"path": "folder/supplement.csv"

},

"confirmEmail": "[email protected]",

"strategy": "updateOnly",

"hasHeader": true

}

Example Request URIs

The following URI in conjunction with the JSON will perform the POST to the supplement cars.

http://<path>/supplements/cars/imports

POST /supplements/{supplement}/records

Method

URI Path

POST

/supplements/{supplement}/records

Creates a new data record in the specified supplement in the Cordial database using the appropriate JSON body.

The record must include values for eachof the indexed fields along with any other optional non-indexed fields of your choosing. The values provided for the indexed fields cannot be empty strings. Posting more than one time for the same record id value within a supplement will update the existing record.

Parameters

*Required

Parameter

Type

Description

Example

*id

string

Unique record ID for each supplement instance. Cannot be a 24 character hex string.

1234212

Additional parameters or fields can be added to the JSON based on your data. This includes the indexed fields previously defined for the supplement and any fields you add as additional fields or fields declared on the fly.

Example JSON Requests

The following will add a supplements record for the supplement with the key of cars. Note that these fields were all indexed fields.

{

"id": "3324",

"make": "Jeep",

"model": "Liberty",

"year": "2007"

}

The following will do the same as above, but will also add a new non-indexed field labeled comment.

{

"id": "3324",

"make": "Jeep",

"model": "Liberty",

"year": "2007",

"comment": "vehicle is accident free"

}

Example Request URIs

The following URI in conjunction with the JSON will perform the POST to the supplement cars.

http://<path>/supplements/cars/records

GET /supplements/{supplement}/records

Method

URI Path

GET

/supplements/{supplement}/records

Retrieves all records for a specific supplement from the Cordial database.

The supplement is defined by the supplement key value.

For example, /supplements/cars/records would return the response data for the supplement with the key value of cars.

Example Request URIs

Return all records of a supplement

The following URI will retrieve all supplement records for the supplement with a key of cars and include all fields.

http://<path>/supplements/cars/records

Return records filtered by field name

The following URI will retrieve all supplement records for the supplement with a key of cars, but only include the field data for model.

http://<path>/supplements/cars/records?fields=model

Return records filtered by multiple field names

The following URI will retrieve all supplement records for the supplement with a key of cars, and include the field data for both model and year.

http://<path>/supplements/cars/records?fields=model,year

Return records filtered by field value

The following URI will retrieve all supplement records for the supplement with a key of cars, and where the value for model is prius.

http://<path>/supplements/cars/records?model=prius

Return records filtered by field value and multiple field names

The following URI will retrieve all supplement records for the supplement with a key of cars, where the value for model is prius, and include the field data for both model and price.

http://<path>/supplements/cars/records?model=prius&fields=model,price

Return records filtered by page number and records per page

The following URI will retrieve all supplement records for the supplement with a key of cars starting from page 3 grouping contacts by 10. For example, page 1 would have included the first 10, page 2 the second group of 10 and so on.

http://<path>/supplements/cars/records?page=3&per_page=10

Return records filtered by last modified date

The following URI will retrieve all supplement records for the supplement with a key of cars by last modified date in ascending order

http://<path>/supplements/cars/ecords?sort_by=ct&sort_dir=asc

Return records filtered by created date

The following URI will retrieve all supplement records for the supplement with a key of cars by date created in descending order

http://<path>/supplements/cars/records?sort_by=ct&sort_dir=desc

PUT /v2/supplements/{supplement}/clear

Method

URI Path

PUT

/supplements/{supplement}/clear

Updates a supplement by clearing all previously added field values. Supplement name, key,and indexes will remain in the Cordial database and the supplement can be updated again with new values for the fields.

The supplement is defined by the supplement key value.

For example, /supplements/cars/clear would clear the field values in the supplement with a key of cars.

Note : Supplements used as contact attributes cannot be cleared using this method.

Example Request URIs

Clear all supplement field entries

The following URI will clear all supplement field values for the supplement with a key of cars.

http://<path>/supplements/cars/clear

GET /supplements/{supplement}/records/{id}

Method

URI Path

GET

/supplements/{supplement}/records/{id}

Retrieves a record for a specific supplement from the Cordial database.

The record is defined by the supplement key value and the record id value.

For example, /supplements/cars/records/33415 would return the response data for the record with the id value 33415 from within the supplement cars.

Example Request URIs

Return records filtered by ID

The following URI will retrieve a supplement record for the supplement with a key of cars and the supplement record id of 33415 and include all fields.

http://<path>/supplements/cars/records/33415

Return records filtered by ID and multiple field names

The following URI will retrieve a supplement record for the supplement with a key of cars, a supplement record id of 33415 and include fields for brand and model.

http://<path>/supplements/cars/records/33415&fields=brand,model

PUT /supplements/{supplement}/records/{id}

Method

URI Path

PUT

/supplements/{supplement}/records/{id}

Updates an existing record in the specified supplement in the Cordial database using the appropriate JSON body.

The record is defined by the supplement key value and the record id value.

For example, /supplements/cars/records/33415 would update the record with the id value 33415 from within the supplement cars. It is possible to update any number of field values.

Parameters

Both existing and additional fields can be included in the JSON based on your data. This includes the indexed fields previously defined for the supplement and any fields you add as additional fields or fields declared on the fly.

Example JSON Requests

The following will update the model field with the value of Grand Cherokee.

{

"model": "Grand Cherokee"

}

The following will do the same as above, but will also add a new non-indexed field labeled annualMilesDriven.

{

"model": "Grand Cherokee",

"annualMilesDriven": 10000

}

Example Request URIs

The following URI in conjunction with the JSON will perform the PUT to the supplement cars with the supplement record id value of 3324.

http://<path>/supplements/cars/records/3324

DELETE /supplements/{supplement}/records/{id}

Method

URI Path

DELETE

/supplements/{supplement}/records/{id}

Deletes a record and its data for a specific supplement from the Cordial database.

The record resource is defined by the supplement's unique key value and the record's unique id value.

For example, /supplements/cars/records/33415 would remove the record with the id value 33415 from within the supplement cars.

Example Request URIs

The following URI will delete a supplement record from the supplement with a key of cars and the supplement record id of 33415.

http://<path>/supplements/cars/records/33415

In this Article

Inbox Placement Test Overview

How Seeds are Sent

Setting Up an Inbox Placement Test

Viewing Inbox Placement Test Results

Inbox Placement Test Overview

Cordial partners with 250OK to provide greater insights into message deliverability. When you enable an inbox placement test, a seed listis automatically sent to a wide variety of email providers when you send your batch message. You are then able to see if your message landed in the inbox for each individual provider.

Note: Inbox placement tests are billed to the account monthly per the amount outlined in your contract.To enable inbox placement tests in your account, please contact your client success manager.

How Seeds are Sent

Unlike other 3rd party deliverability providers, Cordial's integration with 250OK does not require the creation of new contact records for each individual seed to be mailed to. Instead, the seeds are combined with the batch message sending audience via an API call, making test enablement a one-click process.

Once a batch message is sent, the seeds are inserted at random throughout the send. Some providers disperse the seeds at the beginning or end of a send, potentially skewing inbox placement results while Cordial's integration randomly disperses seeds throughout the send which provides more accurate inbox placement results.

Setting Up an Inbox Placement Test

To enable an inbox placement test on a batch message, create a new message or edit a draft message. Then under delivery settings, click edit. You will see the option to enable the inbox placement test as well as the number of tests you have used in the current month.

experiments

Note: Inbox Placement tests may not be compatible with message throttling and .

Viewing Inbox Placement Test Results

To view the inbox placement test results, open a sent message and scroll down to the section labeled "Inbox Placement Test".

You can view the total number of seed addresses, the status of the test and summary results for Inbox, Spam,and Missing (messages that were not delivered or reported as bounced).

Note: the status of the report may say "pending" and will seek to collect results from the inbox seed addresses for up to 72 hours after a message is sent. In most cases, a test is largely considered done after 24 hours.

To view a more detailed list of results per inbox provider, click on any of the summary results boxes.

In this Article

Overview

Give Cordial Permission to Access Your Facebook Account

Overview

The Facebook Custom Audience integration allows you to target Facebook ads to your Cordial contacts by uploading a new or existing audience to Facebook via the UI. Use custom audiences uploaded from Cordial when running ads across multiple placements includingFacebook, Instagram, Audience Network, and the Messenger.

Note: To enable the Facebook Custom Audiences integration in your account, along with the required Data Automations feature, please contact your Client Success Manager.

Prerequisites

Before uploading a custom audience, you must meet the following Facebook prerequisites:

A verified Facebook account that is set up to send ads.

Accepted Facebook’s Custom Audiences Terms.

Give Cordial permission to access your Facebook account.

Give Cordial Permission to Access Your Facebook Account

To upload custom audiences, your Facebook app must give Cordial permission to make requests to Facebook.

Navigate to the Marketplace, located in the account management dropdown.

Find the Facebook Custom Audiences integration card. If the option is not visible, contact your Client Success Manager to have it enabled in your account.

Clicking the Enable button will show options to configure the integration.

Click the Login With Facebook button to log into your Facebook account that is set up to send ads.

Once logged into Facebook, you'll see your Facebook Ad Account ID. If you have multiple ad accounts, you'll see an option to choose the account. The chosen account ID allows Cordial to send custom audiences to Facebook on your behalf.

Click on the Accept Facebook TOS button to accept Facebook's terms.

To complete the setup process, click the Save button. The Facebook Custom Audience integration is now enabled.

Note: If at any time you want to disable Cordial’s access to your Facebook account, click on the Configure button, choose Disable from the check boxes and click Disable.

In this Article

Cordial Extension for Magento Video

Install the Cordial Extension

Configure the Cordial Extension

Enable the Cordial Extension

Add Your Cordial API Key

Add Your Cordial Account Key

Map Customer Attributes

Synchronize Existing Data and Templates

The Cordial extension for Magento Version 2 provides a turnkey solution to connect your Cordial account with your existing Magento V2 storefront for syncing customer behaviors (browse, purchase, etc.), profile data, order data and transactional data in real time.

In addition to data synchronization, the extension enables you to route all Magento promotional, triggered and transactional messages to messages within Cordial.

Cordial Extension for Magento Video

The following video will give you an overview of installing and setting up the Cordial extension for Magento:

map Magento templates

Install the Cordial Extension

Note: The Cordial extension for Magento requires that email address be set as the primary key in your Cordial account.

Contact your CSM to obtain the Magento extension, which can then be installed using the Magento Extension Manager or via the command line.

Learn More about installing using the Magento Extension Manager

Learn More about installing using command line

Configure the Cordial Extension

To get started with the Cordial extension you will need to enable the extension, provide your Cordial API and Account keys, map customer attributes and synchronize any existing Magento data.

Enable the Cordial Extension

In your Magento account, navigate to the Configuration page of the Cordial extension: Cordial > Configuration.

This will take you to the General Settings page. Make sure that your store view is set to Default Config and enable the Cordial extension using the Cordial Integration dropdown.

The JavaScript Listener script editor allows you to modify script parameters depending on your store configuration. For example, if you are using a vanity domain, add it as the data-cordial-url and t.src value to replace the default track.cordial.io entries. This will ensure that all relevant events are being tracked including order revenue attribution.

Add your Cordial API Key

In your Cordial account, on the API Keys page, create an API key by whitelisting the catch-all IP address: 0.0.0.0/0. Learn how to generate an API key

In your Magento account, navigate to the Configuration page of the Cordial extension: Cordial > Configuration.

Choose the Default Store View from the Store View dropdown menu.

Paste the API Key into the Cordial API Key field and click Save Config.

Add your Cordial Account Key

In your Cordial account, copy the account key on the Account Settings page under Account Info.

In your Magento account, on the CordialConfiguration page (set to Default Store View), paste the account key in the Cordial Account Key field and click Save Config.

Your Cordial account should now be connected to the Magento extension and ready to map customer attributes and synchronize data.

Note that when the configuration is saved, the following changes will occur in your Cordial account:

A list called Promotional will be added to your account. Contacts will automatically be added to this list if they subscribe on your Magento store.

The following contact attributes will be added:

lastPurchase

m_wishlist

magentoAlerts

magentoDeleted

Map Customer Attributes

Before synchronizing Magento customers with your Cordial account, you will need to map all desired attributes.

You have the option to map attributes that already exist in your Cordial account, or create new attributes from within Magento and send to Cordial.

Map existing Cordial attribute keys

Navigate to the Cordial Configuration page in your Magento account.

Add the desired Cordial contact attributes keys and the corresponding Magento customer attribute codes in the customer attributes mapping table. Be sure that the Magento attribute codes match the codes in your store. You can view all your existing customer attributes by navigating to Store> Attributes> Customer (available in Enterprise edition only - see table below for a list of standard customer attributes).

You can add more attributes by clicking the Add button. Once all attributes are added, click the Save Config button. Cordial attribute keys that already exist in your account will be mapped.

Below is a list of standard Magento customer attributes codes.

Magento Customer Attribute Code

Description

prefix

Name Prefix

firstname

First Name

middlename

Middle Name/Initial

lastname

Last Name

suffix

Name Suffix

group_id

Group

dob

Date of Birth

default_billing

Default Billing Address

default_shipping

Default Shipping Address

taxvat

Tax/VAT Number

confirmation

Is Confirmed

created_at

Created At

gender

Gender

updated_at

Updated At

Create and map new Cordial attribute keys

Add the desired Cordial attribute keys to the customer attributes mapping table and click Save Config.

Click the Send New Attributes to Cordial button to create and map the new attribute keys.

Synchronize existing Data and Templates

Once your Magento and Cordial accounts are connected, any future data will be automatically synchronized (unless individually disabled). If you have existing data in your Magento account at the time of connection, you can use the Post Data to Cordialoption to post all existing data to your Cordial account. You are also able to post all existing Magento templates into your Cordial account using this method.

Note: you are able to disable syncing of individual products or customers by turning off Cordial Sync on each product or customer edit page.

To post Magento data to Cordial:

Navigate to the Cordial Configuration page in your Magento account and locate the Post Data to Cordial section.

Choose which data collections to post and click the Post Data to Cordial button.

Note: when syncing templates, all template code including necessary external variables (extVars) will be saved into Cordial. You can also to existing templates in Cordial on the Template Mapping page.

You can check the status of the sync by navigating to the Cordial Sync page.

Locate the desired Sync job and check the Todo column. If the Todo column contains the value "nothing", then the sync performed without errors.

If the Todo column contains the value "Sync", then there was a problem with the job.

You can view the status of any job by navigating to the Log page.

Here you can view info on all API calls made to Cordial.

To view specific info on the API call and response, click the Select dropdown and choose View.

Map Transactional Templates

You are able to map Magento templates to automation templates created in Cordial.

Navigate to the Cordial Template Map page in your Magento account.

Click the Map New Template button.

Choose the desired Magento template and Cordial templates to map from the drop down menus.

Click the Save Template button.

You can also edit existing template mapping.

Click on the desired template to edit in the template list.

Select new templates from the dropdown menus and click save.

Congratulations, your Magento account is now configured and connected to your Cordial account!

In this Article

Install the Cordial Extension

Configure the Cordial Extension

Enable the Cordial Extension

Add Your Cordial API key

Add Your Cordial Account Key

Map Customer Attributes

Synchronize Existing Data and Auto Map Templates

The Cordial extension for Magento Version 1 provides a turnkey solution to connect your Cordial account with your existing Magento V1 storefront for syncing customer, order and transactional data in real time. In addition to data synchronization, the extension also enables you to route all Magento promotional, triggered and transactional messages through Cordial.

Install the Cordial Extension

Download the Cordial Extension and follow the instructions within the included read me file.

Configure the Cordial Extension

Note: The Cordial extension for Magento requires that email address be set as the primary key in your Cordial account.

To get started with the Cordial extension you will need to enable the extension, provide your Cordial API and Account keys, map customer attributes and synchronize any existing Magento data.

Enable the Cordial Extension

In your Magento account, navigate to the Configuration page of the Cordial extension: Cordial > Configuration.

template mapping

This will take you to the General Settings page. Make sure that your strore view is set to Default Config and enable the Cordial extension using the Cordial Integration dropdown.

Add Your Cordial API Key

In your Cordial account, on the API Keys page, create an API key by whitelisting the catch-all IP address: 0.0.0.0/0. Learn how to generate an API key

In your Magento account, navigate to the Configuration page of the Cordial extension: Cordial > Configuration.

Choose the desired store from the Current Configuration Scope dropdown menu.

Paste the API Key into the Cordial API Key field and click Save Config.

Add your Cordial Account Key

In your Cordial account, copy the account key on the Account Settings page under Account Info.

In your Magento account, on the CordialConfiguration page, paste the account key in the Cordial Account Key field and click Save Config.

Your Cordial account should now be connected to the Magento extension and ready to map customer attributes and synchronize data.

Note that when the configuration is saved, the following changes will occur in your Cordial account:

A list called Promotional will be added to your account. Contacts will automatically be added to this list if they subscribe on your Magento store.

The following contact attributes will be added:

lastPurchase

m_wishlist

magentoAlerts

magentoDeleted

Map Customer Attributes

Before synchronizing Magento customers with your Cordial account, you will need to map all desired Magento customer attributes to their corresponding Cordial contact attributes.

You have the option to map attributes that already exist in your Cordial account, or create new attributes from within Magento and send to Cordial.

Map existing Cordial attribute keys

Navigate to the Cordial Configuration page in your Magento account.

In the Customer Attributes Mapping table, add the desired Cordial contact attribute keys and then select the corresponding Magento customer attributes you would like to map using the drop down menu. Be sure to use the Cordial contact attribute key (versus the name) when mapping.

You can add more attributes by clicking the Add New Row button. Once all attributes are added, click the Save Config button to save the configuration and map the specified attributes.

Create and map new Cordial attribute keys

Add the desired Cordial attribute keys to the customer attributes mapping table and clickSave Config.

Click theSend New Attributes to Cordialbutton to create and map the new attribute keys.

Synchronize Existing Data and Auto Map Templates

Once your Magento and Cordial accounts are connected, any future data will be automatically synchronized (unless individually disabled ). If you have existing data in your Magento account at the time of connection, you can use the Post Data to Cordialoption to post all existing data to your Cordial account. You are also able to automatically map all Magento templates to existing Cordial automation templates (with matching message keys) using this method.

Note: To populate your Cordial account with all Magento templates and necessary code (HTML and Smarty variables), please contact your Client Success Manager.

Post Data to Cordial:

Navigate to the Cordial Configuration page in your Magento account and locate the Post Data to Cordial section.

Choose which data collections to post and click the Post Data to Cordial button.

Note: When automatically mapping templates using this method, automation templates with matching message keys must already exist in your Cordial account (contact your Client Success Manager for more info). You can also manually map Magento templates to existing templates in Cordial on the page.

Check the status of the sync by navigating to one of the sync pages in the Cordial menu: Product Sync, Customers Sync or Orders Sync.

Locate the desired item and check the Sync column. If the Sync column contains the value "success", then the sync performed without errors.

To view synchronization details, navigate to the Log Manager page.

Here you find details on all API calls.

To view more details click on an individual API call.

Disable sync on individual items:

Navigate to one of the sync pages: Product Sync, Customers Sync or Orders Sync.

Select the desired item(s) and in the Actions menu, choose Unsync and Add to Ignore List and click Submit.

Map transactional templates

On the Template Map page, you are able to map Magento templates to automation templates created in Cordial. To populate your Cordial account with all Magento templates and necessary code (HTML and Smarty variables), please contact your Client Success Manager.

Navigate to the Cordial Template Map page in your Magento account.

Click the Map New Template button or choose an existing template mapping.

Select the desired Magento template and Cordial template to map from the drop down menus.

Click the Map Template button.

Congratulations, your Magento account is now configured and connected to your Cordial account!

In This Article

Enable the Segment Integration

Enable the integration using an API call

Supported Segment Functions

Identify

Add or remove contacts from Cordial lists

Group

Track

Page

Optional Advanced Configuration

Enable the Segment Integration

Activate the Destination Using a Cordial API Key

Create an API key in your Cordial account using the wildcard IP address of: 0.0.0.0/0. Learn more about creating API keys in Cordial.

Log into your Segment account.

Once logged in, paste this URL into your browser:

https://app.segment.com/WORKSPACE/destinations/catalog/cordial

Replace WORKSPACE with your Segment workspace name.

In the example below, WORKSPACE is acme (use all lower case).

Cordial lists

Paste in your Cordial API key and activate the destination.

Note: Certain Cordial attributes designated to store segment attribute values may need to be created as unique and sparse index fields. Please contact your Client Sucess Manager for additional assistance.

Enable the integration using an API call

In order to enable the integration in your Cordial account, you must make the following API call:

POST https://admin.cordial.io/api/integrations/segment

Method

URI Path

POST

https://admin.cordial.io/api/integrations/segment

Enables the Segment integration using the appropriate JSON body.

Parameters

* Required

Parameter

Type

Description

Example

*name

string

The name of the integration to be enabled. "segment" should be used to enable the Segment integration.

segment

*enabled

boolean

Enables or disables the integration.

true or false

Supported Segment Functions

Cordial supports the identify, track, group, andpage methods.

Data should post to: http://integrations.cordial.io/segment

Identify

Segment data is passed through to Cordial using this endpoint, where user in the URL parameters should be set to the Segment API key. userId in the dataset will be saved to a Cordial attribute designated to store the Segment identifier.

If the userId passed is valid and known, the contact in Cordial will be updated with any mapped values set up in the integration. Based on the example configuration above, first_name, userId, address.state, and email will populate or replace the corresponding values in Cordial.

If the userId passed is valid but does not correspond to a Cordial contact, the contact will be created and assigned any mapped values.

If the userId passed is invalid, an error will be returned.

Add or remove contacts from Cordial lists

To make the process of adding and removing contacts from existing more efficient, the list names can be prefixed bygrp_and passed as traits of an identify call.Lists prefixed bygrp_accept the following values: 1 and 0or true and falseto indicate if a contract should be added or removed from the list.

The example below demonstrates how to add a new contact to existing CordialWelcomeSeries and NewUsers lists. To remove a contact from your lists instead, simply use 0 or false values in place of 1 and true.

Note:List names prefixed by grp_ must match the names of your lists in Cordial. If the list names do not match, or the lists do not already exist in Cordial, the request will not be successful.

"traits": {

"grp_WelcomeSeries": 1,

"grp_NewUsers": true

}

Group

Supported data parameters:

Segment key

Type

Cordial mapping

userId

string

email or custom identifier

groupId

string

list ID

If the userId passed is valid and known, and the groupId passed is valid and known, the contact will be added to the list in Cordial.

If the userId passed is invalid, an error will be returned.

Note: Make sure that there is a minimum delay of 5 seconds between theidentify call and thegroup call for new users.

Track

Supported data parameters:

Segment key

Type

Cordial mapping

userId

string

email or custom identifier

event

string

event name

properties

object

event properties (optional)

If the userId passed is valid and known, the event and its properties will be attributed to the contact in Cordial.

If the userId passed is invalid, an error will be returned.

Page

Supported data parameters:

Segment key

Type

Cordial mapping

userId

string

email or custom identifier

If the userId passed is valid and known, a page view event will be attributed to the contact in Cordial.

If the userId passed is invalid, an error will be returned.

Optional Advanced Configuration

PUT https://admin.cordial.io/api/integrations/segment

Method

URI Path

PUT

https://admin.cordial.io/api/integrations/segment

Updates the Segment integration using the appropriate JSON body.

You can remap segment fields using the optional attributeMapping parameter.

Parameters

* Required

Parameter

Type

Description

Example

attributeMapping

Comma separated array of 2 name/value pairs.

Used to remap Segment fields to Cordial attribute keys.

true or false

ignoreFields

Array of comma separated values.

Used to blacklist Segment fields from being passed to Cordial.

["website"]

Example JSON Request (with attributeMapping and ignoreFields)

The following will remap Segment fields to existing Cordial attribute keys and ignore the "website" field.

{

"name":"segment",

"enabled":true,

"attributeMapping":[

{"segmentField":"first_name","cordialKey":"fname"},

{"segmentField":"user_id","cordialKey":"extid"},

{"segmentField":"address.state","cordialKey":"state"},

{"segmentField":"email","cordialKey":"channels.email.address"}

],

"ignoreFields":["website"]

}

GET https://admin.cordial.io/api/integrations

Retrieve a JSON list of integrations you have set up with Cordial.

Configuring an Amazon Kinesis Data Stream allows you to export, process and analyze Cordial event data as it is being created, enabling you to respond instantly instead of having to wait for your data to be collected, packaged and delivered through one-off or recurring exports.

Learn more about Amazon Kinesis

Once your Kinesis Stream is up and running, Cordial will place all Contact Activities, ( system events and customnamedevents ) onto the Kinesis Stream in real-time, as they are created.

Clients may read (consume) the events directly from the stream with their own custom processes, with the help of Amazon's Kinesis Data Firehose product, or both.

The following steps are needed to set up your Kinesis Stream:

Client creates a Kinesis Stream and allows Cordial to write to the stream.

Client enables the Amazon Kinesis Integration in the Cordial Marketplace.

Client begins consuming the stream.

For many use cases, Cordial recommends using Kinesis Data Firehose to help with consumption of the stream, particularly when the destination will be Redshift, S3, Amazon Elasticsearch Service, or Splunk.

Prerequisites:

You must have an AWS account along with permissions to create a Kinesis Data Stream, IAM Policies, and IAM Users.

Create a Kinesis Stream

Detailed instructions to creating and managing the stream can be found on the AWS website.

At the time of this writing, if you are using the AWS Management Console to create the stream, you can go directly to the Console Home Page and click the Create Data Stream button.

Give the stream a name (e.g. cordial-events).

Enter the number of shards to use for the stream.

Note: There are limits to the rate that a single shard can be written to/read from, so you should adjust this number based on your expected traffic levels and event types. It is possible to resize the number of shards later.

Go to the Kinesis Firehose page in your AWS Management Console

After clicking Create Stream button, you should see it (being) created in the list of streams in your account. Click the stream name in the list to view its details.

Note the Stream ARN as you will need this value in the following Create Policy step.

Create an IAM Policy

Create an IAM policy that allows (just) writing to the stream.

Go to the Policies page on your AWS console.

Click Create Policy button.

Click the JSON tab.

Enter the following JSON and replace ARN_from_step_1 with the Stream ARN value from step 1.

{

"Version": "2012-10-17",

"Statement": [{

"Effect": "Allow",

"Action": [

"kinesis:PutRecord",

"kinesis:PutRecords",

"kinesis:DescribeStream",

"kinesis:ListShards",

"kinesis:ListTagsForStream"

],

"Resource": "ARN_from_step_1"

}]

}

Click the Review policy button, give the policy a name (e.g. cordial-kinesis-write-access) and click Create.

Create an IAM User

Create an IAM user and allow cordial to write to the stream.

Go to the Users page in your AWS Management Console

Click Add User button.

Enter a user name (e.g. cordial-kinesis-writer).

Select the checkbox to give it programmatic access, then click the Next: Permissions button.

Select the Attach Existing Policies Directly category.

Search for and select the name of the Policy created in step 2.

Click the Next: Review button.

Click Create user button.

You'll see a success message with options to view or download the access credentials for this user. You will need to supply these when enabling Kinesis integration in the Cordial Marketplace.

Complete Configuration in the Cordial Marketplace

After obtaining all of your AWSaccess credentials, visit the Cordial Marketplace to enable Amazon Kinesis Integration with your Cordial account in order to write to your stream.

From this point, you simply need to supply the Kinesis Stream Name,AWS User's API Key and AWS User'sSecret Access Key when prompted. Once configured, Cordial events will begin appearing in your Kinesis Stream.

Note: We also support an exclusion filter if you would like to exclude certain events from being added to the stream (probably not recommended for most use cases).

Set Up Kinesis Firehose (optional)

Depending on the use case, you may find it helpful to have Kinesis Firehose automatically consume the stream and copy the events to a particular destination.

.

Click the Create Delivery Stream button.

Give the delivery stream a name (e.g. cordial-events-delivery).

For Source, choose the Kinesis Stream radio button.

In the Kinesis Stream drop-down, select the Kinesis Stream created for Cordial.

Click Next, and follow the AWS wizard to finish setting up your Firehose delivery system.

Note: These steps will vary depending on whether or not you need to convert or transform the data and your selected delivery destination.

Define Destination

Choose the preferred destination.

Send data to S3

From here your developers would write code to consume the data from S3.

Send data to Redshift

Send data to Redshift and configure any transformations and how you'd like the data to load.

From here your developers map the data into Redshift.

Developers/Marketers/BI Partners will work together to configure Redshift as a source for the BI tool (Domo, Looker, Tableau, etc.).

Send data to your own or other database for storage

From here your developers map the data into the database.

Developers/Marketers/BI Partners would work together to configure the Database as a source for the BI tool (Domo, Looker, Tableau, etc.).

Things To Note

By default, Kinesis is 24-hour stream but can be configured up to a 7-day stream. If you choose to use Firehose consumer, then 24 hours is acceptable.

Data collection starts from the time of configuration. Historical data cannot be extracted using this method.

In this Article

Overview

Create a Google Service Account

Enable the Google Cloud Storage Integration

Using Google Cloud Storage

Overview

The Google Cloud Storage integration allows you to use Google Cloud as a source for importing and exporting data into and out of your Cordial account using either the user interface (UI) or the API.

Once the integration is successfully enabled, you will see a new option for Google Cloud Storage on data import and export pages within the UI, and as a source or destination parameter in the API.

Create a Google Service Account

Before you are able to enable the integration, you must first create a Google Service Account in your Google Cloud Platform.

In your admin panel, navigate to Service accounts, give the account a name and an ID and click Create.

exporting

Define a Role for your service account.

Create and download a JSON key.

Confirm the key has the admin rights to the bucket.

Enable the Google Cloud Storage Integration

Once you have created a service account and downloaded the key in JSON format, you can enable the integration in the Cordial Marketplace.

Navigate to the Marketplace, located in the account management dropdown.

On the Marketplace page find the Google Cloudintegration card.

Click Enable to edit the configuration. You will see a list of configuration settings to complete in order to enable the integration.

Bucket Name - Enter the name of your Google Cloud Bucket.

Bucket Description - Give a brief description of the Google Cloud Bucket.

Upload Key File - Upload the key file downloaded from your Google Cloud Storage account.

Using Google Cloud Storage

Once the Google Cloud Storage is set up successfully there will be options to use Google Cloud when importing and exporting contacts via the UI as well as the API.

Import Via the UI

When importing contacts in the UI, there will be an option for Google Cloud as an input source.

Export Via the UI

When exporting contacts in the UI, there will be an option to Send file to Google Cloud as an export destination.

Via the API

Once enabled, Google Cloud will be a source option for importing and exporting contacts using the API. View the API documentation for importing or contacts.

In This Article

Overview

Configure the Amazon Kinesis Data Stream

Enable the Amazon Kinesis Integration

Overview

The Amazon Kinesis Integration allows you to continuously stream real-time Cordial Contact Activities ( system events and customnamedevents ) directly to your Amazon Kinesis Data Stream. A number of Amazon supported, or custom-built, services can be used to package and analyze incoming data, giving you an additional layer of real-timeactionable insights.

Note: The use of Amazon Kinesis may cause a noticeable drop in message send performance due to data transfer rate limitations. This is especially the case when large quantities of message sent events are being replicated and consumed by the Kinesis integration.

Configure the Amazon Kinesis Data Stream

Before Amazon Kinesis Integration can be enabled, you must first configure a Kinesis Data Stream from the AWS Management Console, as well as create anAWS Identity and Access Management (IAM) policy and user.

Enable the Amazon Kinesis Integration

Once you have configured your Kinesis Stream and created the necessary access credentials, you can enable the integration in the Cordial Marketplace.

Navigate to the Marketplace, located in the account management dropdown.

On the Marketplace page, find the Amazon Kinesisintegration card.If you don't see the Kinesis card in your account, contact your CSM to have it enabled.

Click Enable to edit the configuration. You will see a list of configuration settings to complete in order to enable the integration.

Kinesis Stream Name - Enter the name of your Kinesis Data Stream.

Kinesis (AWS) API Key - Provide the AWS user's API key.

Kinesis (AWS) Secret - Provide the AWS user's secret access key.

Region - Indicate the AWS region of your Kinesis Stream.

Once the configuration is saved, event data collection from your Cordial account into your Kinesis Data Stream will begin immediately.

Note: Data collection starts from the time of configuration. Historical data cannot be extracted using this method.

In This Article

Overview

Install and Setup

Install the Cordial app in your Shopify account

Enter your API and account keys

Install the JavaScript listener

Map Attributes to Cordial

Map to Array Attributes in Cordial

Synchronize Product, Customer, and Order Data

Manually synchronize data

Automatically synchronize data

Check for synchronization errors

Overview

The Shopify integration allows you to connect your Shopify store to your Cordial account for seamless exporting of customer, product and order data.

Cordial's redesigned Shopify app delivers numerous infrastructure improvements targeted at app performance, stability and availability. This update includes support for AJAX cart calls and the ability to customize Cordial attributes to match default Shopify data fields.

Once the integration is set up, attributes mapped and data synchronized, you will be able to build audiences, trigger messages and personalize message content based on products, customers and order data from your Shopify account.

Install and Setup

Install the Cordial app in your Shopify account

Navigate to https://shopify-integration.cordial.com and enter your Shopify shop URL to install the Cordial app.

automated recurring synchronization

Give permission to install the app in your account.

Enter your API and account keys

In your Cordial account, create a new API key for the catch-all IP address 0.0.0.0/0. Learn how to generate an API key.

On the Cordial Administration page in Shopify, enter your API key and click the Testbutton to check the API connection in your Cordial account.

Enter your Cordial Account Key. You can find your Account Key on the Account Settings page in the Cordial platform.

Click Save.

Install the JavaScript Listener

Installing the JavaScript listener enables Shopify to post data to your Cordial account. The posted data consists of custom events, cart items and orders.

The following custom events and related properties will be available once the JavaScript listener is installed:

Custom Event Name

Related Properties

browse

url, source, product, category

cart

url, source, page

order

source, orderID

Custom events (browse, cart, and order) can not be renamed.

To install the JavaScript listener, click theInstall JS Listenerbutton located in the Quick Actions menu on the Cordial Administration page.

Warning: If in the past you manually set up the JS Listener for your Shopify site, you can skip the installation step. Under these circumstances, installing the script using the install button will double the calls for browse, cart and order events.

You can Edit the JavaScript base scriptto modify script parameters depending on your store configuration. For example, if you are using a vanity domain, add it as the data-cordial-url and t.src value to replace the default track.cordial.io entries. This will ensure that all relevant events are being tracked including order revenue attribution.

Congratulations, your Shopify account is now connected to Cordial! Continue reading below to learn how to map contact attributes and synchronize product, customer and order data.

Map Attributes to Cordial

Once the Cordial app is connected to your account, you can start mapping Shopify customer fields to your contact attributes in Cordial.

Order and product attributes that are unique to Shopify and do not exist in Cordial will be stored as additional properties of the respective Cordial order or product data collections.

Note: All available Shopify Customer Fields should be mapped to Cordial attributes to ensure all data is properly transferred during synchronization. All Cordial attributes must be unique. Duplicate attribute values are not supported.

Note: After connecting the app, please ensure that the Shopify email attribute is mapped to Cordial's channels.email.address attribute.

Navigate to the attribute mapping page by choosing Key Mapping from the Main Menu dropdown in the top right of the Cordial Administration page.

On the Attribute Mapping page, choose a Shopify field you wish to map from the dropdown menu. The selected field will automatically be added to the top of the existing list of keys.

Enter the corresponding Cordial contact attribute name to the right of each Shopify customer field.

Note: Cordial contact attributes you wish to map must already exist in your Cordial account. Attributes that do not exist in your Cordial account will not be created automatically.

You can Test your key mappings to check for errors.

Click Save once all Shopify customer fields are mapped to their corresponding Cordial contact attributes.

Note: The Reset to Default Mappings button will reset all key mappings for first name, email and subscribed status fields to their default values.

Map to Array Attributes in Cordial

You can map Shopify customer fields to array type contact attributes in Cordial using the split(,) array modifier.

For example, to map the Shopify customer tags field to the Cordialtagscontact attribute, use tags|split(,) within the Shopify key mapping field. Shopify customer tags will be inserted as an array into the Cordial tags contact attribute.

Synchronize Product, Customer, and Order Data

When synchronizing data from Shopify to Cordial, there are two options: manual synchronization and . Normally, you would use the manual method to perform a one-time syncchronization of historical data, and then set a recurring schedule for all future automated data posts. Note that these data synchronizations use API calls to post data.

Note: Shopify contacts without an email address on file will be excluded from synchronization to Cordial. These contacts can be synchronized during the next manual or automated synchronization job after the profile email address has been added in Shopify.

Synchronization is a One-Way Post

Note that synchronization is a one-way post of contact, product and order data. Data is posted from Shopify to Cordial and not in reverse. For example, if a contact attribute is updated in Cordial (i.e. first name), it will not be updated in Shopify.

Synchronizing Subscribe Status

The synchronization of subscribe status changes depending on the contact's status in Cordial. Shopify key for email subscribe status is accepts_marketing: yes/no, which is mapped to Cordial's email subscribe status key of channels.email.subscribeStatus: subscribed/unsubscribed.

The table below displays how subscribe status is updated after synchronization:

Contact exists in Cordial

Subscribe Status in Cordial

Subscribe Status in Shopify

Subscribe Status in Cordial After Synchronization

No

N/A

Accepts email marketing

Subscribed

No

N/A

Does not accept email marketing

None

Yes

None

Accepts email marketing

Subscribed

Yes

Subscribed

Does not accept email marketing

Subscribed(Subscribe status is not overwritten)

Yes

Unsubscribed

Accepts email marketing

Unsubscribed (Subscribe status is not overwritten)

Note above that if a contact has unsubscribed from receiving promotional emails in Cordial, it is not possible to change the subscribe status tosubscribed as a result of a Shopify synchronization. Also, if a contact is subscribed in Cordial, it is not possible to change subscribe status to noneas a result of a Shopify synchronization.

Manually synchronize historical data

After mapping attributes to your Cordial account, you should synchronize all desired historical data from Shopify. This will ensure that your Cordial account is up to date with product, customer and order data from your Shopify account.

Navigate to the Cordial Admin page from the Main Menu dropdown.

On the Cordial Administration page, locate the Jobs section and click Run Now for the desired data collections under the Sync All heading. Doing so will synchronize all historical data in the selected collection, regardless of creation date.

Note: The Last Sync timestamp is based on the user's local timezone.

Automatically Synchronize Data on a Recurring Schedule

Once you have manually synchronized your data, you can set a recurring interval to automatically synchronize any new and updated data moving forward.

In the Jobs section of the main Cordial Administration page, enter the recurring synchronization interval in minutes (2 minute minimum) for each data collection and click Enable. To disable a running synchronization, click the corresponding Enabledbutton.

Note:Historical data will not be synchronized to Cordial when the Recurring Sync begins. Only new and updated data since the last synchronization will be posted.

Check for synchronization errors

API call errors can cause data not to post successfully to your Cordial account.Navigate to the Job Logs page where API errors will be listed, along with past synchronization jobs.

The Job Logs page will list the last 100 jobs. Use the Refresh button in case your recent jobs are not listed immediately.

Note: The job start and end timestamps are based on user's local timezone.

Congratulations! Your Shopify account is now configured and synchronized with your Cordial account. You'll now be able to build audiences and trigger messages based on data collected from your Shopify store.

In this Article

Overview

Enable the Google Ads Integration

Overview

The Google Ads integration allows you to target Google ads to your Cordial contacts by uploading new or existing audiences to your Google Ads account via the UI. Use custom audiences uploaded from Cordial when running ads across multiple Google Ads networks and campaign types includingthe Search Network, YouTube, Display Network, and App engagement (depending on your Google Ads account eligibility).

Note: To enable the Google Ads integration in your account, along with the required Data Automations feature, please contact your Client Success Manager.

Prerequisites

Before uploading a custom audience, you must meet the following prerequisites:

Have a verified Google Ads account that is set up to send ads.

Enable the Google Ads integration in Cordial Marketplace.

Enable the Google Ads Integration

Follow these steps to enable the Google Ads integration in Cordial.

Navigate to the Marketplace, located in the account management dropdown.

Find the Google Ads integration card. If the option is not visible, contact your Client Success Manager to have it enabled in your account.

Clicking the Enable button will show options to configure the integration. Provide your Google Ads account ID and Save.

If multiple users are managing Google Ads accounts, click the Switch Accounts button to log in as a different user.

The Google Ads integration is now enabled.

Note: If at any time you want to disable Cordial’s access to your Google Ads account, click on the Configure button, choose the Disable option, and click Save.

In This Article

Overview

Prerequisites

Create a New Data Job

Specify the Data Source

Choose Your Audience

Map Audience to the Social Audiences Integration

Map Contact Attributes

Upload a One-Time Audience

Publish Audience Automation

Schedule Audience Automation

Enable Audience Automation

Performance Results

Overview

Social Audiences Automations allow you to target social media ads to your Cordial contacts by uploading new or existing Cordial audiences to supported social media networks via the UI. Social audiences can be uploaded as static one-time data jobs or as dynamic data automations on a recurring schedule of your choice.

One-time static audience uploads can be used to target and analyze narrowly defined groups of contacts or buyer personas. You may want to create static audience segments based on past behaviors such as past purchases of a limited-time product that is being reintroduced. You may also use insights gained from analyzing static audiences to determine where to focus your time when it comes to social media targeting.

Recurring audience automations will continually update audiences of your choice with the latest Cordial subscribers. Apply your already effective email marketing strategies more broadly by reusing existing email lists and audience segments to create new opportunities on social media.

Note: To enable specific social audiences integrations in your account, along with the required Data Automations feature, please contact your Client Success Manager.

Prerequisites

Before uploading a custom audience, the following prerequisites must be met:

Have a verified social media account that is set up to send ads.

Enable supported social media integration in your Cordial account.

Accept any terms and conditions required by the social network.

Create a New Data Job

Once your social audiences integration is fully configured, you can begin creating one-time and recurring audience uploads. If you plan on working with multiple recurring audience uploads, you will need to create a recurring data job for each audience.

Navigate toData Jobs>Create New Data Job.

SelectOne-timeto create and upload a static one-time audience orRecurringto create a continually updating dynamic audience.

Note: While audience counts in Cordial are dynamic and may change over time, one-time audience uploads will remain static with the audience count at the time they were uploaded.

content versioning

Name- Give your new data job a recognizable name. This value will appear on the Data Job Automations page in Cordial as well as your external social audiences account (e.g., Facebook Audiences page in Facebook Business Manager or Audience lists under Audience manager in Google Ads).

Key- Unique identifier used to reference this data job in API calls. The key will auto-populate but the value can be edited. Only available for recurring automations.

Tags- Tags are useful for grouping data jobs together (similar to folders). This field accepts new and existing tag names.

In the steps to follow, you will configure properties for data source, data mapping, and data destination, all of which are instructions telling Cordial what to do with your chosen audience. When creating a recurring audience automation, you will also schedule how often and when to run the automation.

Specify the Data Source

We are working with Internaldata (contacts and audiences saved in Cordial) and this data is part of the Contacts data collection.

Choose Your Audience

Using the Audience Builder, choose which contacts from your Cordial account should be part of this social audience. You can load a previously saved Cordial audience by selectingLoad Saved Audiencesor build one from scratch using a combination of rules.

Tip: Custom Facebook and Google audiences uploaded from Cordial can be used to create Lookalike Audiences (Facebook) and Similar Audiences (Google). Your custom audiences should consist of at least 100 contacts. The larger the audience, the more matches can be found.

Savethe audience to proceed.

Map Audience to the Social Audiences Integration

In theData Mappingsection, you can set instructions for what happens to the selected data. In this example, we are exporting an audience from Cordial to Facebook using the enabled Facebook Custom Audiences integration.

Choose the appropriate social audiences integration as theDestinationfor your audience.

You can optionally send job status notifications to one or more email addresses. Email notifications will contain data job performance results including completion date, job status, total records added, and total records removed. If this is a recurring audience automation, a separate email notification will be sent for every audience upload on a recurring schedule.

Map Contact Attributes

If the social audiences integration requires contact attribute mapping before the upload takes place, the UI will present you with attribute mapping fields when you choose the destination with this requirement.

Using the Google Ads integration as an example, either contact email or phone number attribute must be mapped in order for your audience to be accepted. You can optionally map all requested attributes.

Simply select the Cordial contact attribute from the dropdown menu that corresponds with the requested integration attribute and save your selection.

Upload a One-Time Audience

One-time audience uploads can be run as soon as the data source, data mapping, and data destination are configured. Unlike recurring audience automations, one-time audiences do not have to be scheduled, published, or enabled.

TheRun data jobbutton will become available once the required content is provided.

Publish Audience Automation

Before publishing, the audience automation is labeled as a draft. Publishing saves your configuration settings for the time being, at which point you are ready to schedule and enable the automation.

You can change the initial configuration settings at any time by copying the published automation to draft, making the necessary changes, and publishing it once again. Previously published versions will be saved under thePast Versionstab. Learn more about .

Schedule Audience Automation

Now that the recurring audience automation is fully configured and published, it’s time to schedule how often and when audience uploads will occur.

Navigate toRecurringlocated in the left sidebar.

Schedulerecurring audience automations by specifying upload frequency, time of day and start date. You can specify anend dateif your campaign is running for a specific period of time. Otherwise, you can leave this option disabled and your audience will continue to synchronize until manually disabled.

Schedule interval- Choose from a list of intervals grouped by hourly, daily, weekly, and monthly categories.

Schedule time- Set the time of day recurring uploads will run. The time zone is set globally based on the main Cordial account time zone settings.

Start date- Select the upload start date.

End date- Enable this option if your audience is tied to a campaign with a known end date. Audience uploads will stop after this date.

Enable Audience Automation

Enabled audience automations will run automatically according to the set schedule. You can change the schedule at any time without disabling the automation.

ClickEnable, and if everything is set up correctly, you will see a notification that the data job has been saved successfully. Your first audience upload will occur on the date and time you indicated in the schedule.

Performance Results

Cordial audiences aredynamicin nature and audience counts can vary over time due to changes in contact attribute values, purchases, custom events, subscribe and unsubscribe events, etc.

One-time audience uploads create a snapshot of the audience at a specific point in time. Changes to the original Cordial audience may occur over time, but one-time audience uploads in your external social audiences account will remain unchanged. To refresh the contact count of one-time audience uploads, they will need to be deleted and uploaded again.

Results for one-time audience uploads includeupload date,statusandtotal added:

Recurring audience automations keep your social audiences updated with valid Cordial subscribers automatically. Any contacts who have been added to the Cordial audience since the last upload will also be added to the existing social audience. Contacts who were previously uploaded to the social audience, but are no longer part of the Cordial audience, will be removed from the social audience.

Results for recurring audience automations will consist of a new entry for every upload as it occurs according to the schedule. The results are listed starting with the most recent upload:

Date- Date and time stamp when the upload occurred.

Status- Upload status. Can be complete or failed.

Total Added- Number of contacts added to the audience. Can be 0 if no new contacts were added to the Cordial audience since the last upload.

Total Removed- Number of contacts removed from the audience. Can be 0 if no contacts were removed from the Cordial audience since the last upload.

Web Form's coupon feature allows you to display coupon codes to your website visitors. Here is a brief overview of how to utilize the coupon feature.

Upload and Load:You can upload a set of one-time-use coupon codes and have them dynamically display in a lightbox. You can easily add more coupon codes as your business needs demand.

Display on any page:The coupon codes can be displayed on a Lightbox's Thank You page, which is displayed after the user submits their email address, or on the main page of the lightbox.

IP Address Based:Each coupon code is IP-address-based, which means a user can't reload your website with the intention of accessing multiple coupon codes. Any given IP address will yield only one coupon code.

Multiple Coupon Code Banks:You can associate a different bank of coupon codes to each lightbox.

Here is how you set it up:

1. Click on Coupons in the Name drop down menu.

2. Click on New Coupon Group. Fill in the fields for Group Name and Offer Description and choose whether you want the coupon to populate when the lightbox is displayed, or when the user submits their info. You can change the populate coupon on setting later using the edit link on the Coupons page. Click on Create Coupon Group.

Box Submit:If you're submitting the coupon as a hidden custom field, or showing it on the Thank You page, be sure the Populate Coupon On field is set to On Submit for your code bank.

Box Display:If you're showing the coupon on the main page of the lightbox, be sure the Populate Coupon On field is set to On Display. Special Note: If you use Box Display, this means every time your lightbox displays, it will use one of your coupon codes. This means if your lightbox displays 10,000 times, it will use 10,000 coupon codes (a new coupon code every time the lightbox displays). Make sure you add a sufficient number of coupons when using using Box Display.

3. Copy and paste all the coupon codes in a comma-separated format:

That means like this:

Coupon1,Coupon2,Coupon3,

It doesnotmean:

Coupon1

Coupon2

Coupon3

4. Click Add to Group

5. Take Note of the Group ID. In this screenshot you will notice it is Group ID 80

6. In the Editor, you can add [COUPON_{GROUPID}], so in this case it would be [COUPON_80]

7. This will work in Text, Buttons, and HTML boxes (Please see special notes on using Coupon Codes in HTML Block)

8. You can add coupons, but you can't remove coupons.

9. You can remove a Coupon group, but that will remove all coupons in that group

10. It automatically uses IP addresses. So, the same IP address will always see the same coupon code (as long as it is within that group). This prevents abuse and fraud of coupons

11. You can see the percentage of coupons remaining, once it goes below a certain amount, we recommend adding more coupons by clicking on “Add Coupons”

We recommend adding no more than 5,000 coupons at once. You can add as many batches of coupons as you’d like to a code bank.

We also recommend setting up notifications so you can replenish them before they run out. Notifications are sent out when there are 10\% coupons remaining.

*********

Checklist

Be sure to double check the following before making your coupon lightbox live.

1. Created a new coupon group

Made sure it is “Box Submit” if you are showing the coupon code on the Thank You page or Passing it as a hidden field. (this makes sure we only use the coupon on submit not on display)

2. Uploaded all the coupons into the group (try to upload 1,000 coupons at a time, for best results. Max limit is 5000 coupons per time)

3. Updated the new coupon merge tag on to the Thank You pages of the Lightbox. This will make sure the coupon code is displayed in the Thank You Page

4. Updated the Hidden Field CUSTOM_10 to pass the COUPON_29 field

We used CUSTOM_10 field, but you can use any custom field and make it a “Hidden Field”

If your coupons are formatted as a column in excel, follow these steps to get them in the correct comma delimited format:

1. Copy column from excel

2. Open word and paste text only

3. Open the Find and Replace menu. Replace all instances of ^p with,

4. Wait patiently! This part can take a while.

5. The codes are now comma delimited!

TECHNICAL NOTES ON ADDING COUPON CODES TO HTML BLOCKS:

If you ever add Coupon merge tags to the “HTML” elements in the editor, that HTML element must fulfill at least one of these requirements:

1) Have no other HTML embedded within it at the same level as the Coupon merge tag. (ie. Coupon merge tag must be contained within the lowest child HTML element).

or

2) Wrap the Coupon merge tag within its own “div” tag or “button” tag (only these 2 will work for now).

I would typically recommend always doing #2 just to be safe.

FAQ / Testing Notes:

Q: I keep getting the same coupon code when I submit my test email? Why is that.

A: Our system will only give out 1 coupon code to 1 IP Address. This prevents abuse on users trying to grab more than one coupon code. You will keep getting the same coupon code if you submit multiple emails on the same IP address

POST /automationtemplates

GET /automationtemplates

GET /automationtemplates/{key}

PUT /automationtemplates/{key}

POST /automationtemplates/{key}/publish

POST /automationtemplates/{key}/senddraft

POST /automationtemplates/{key}/send

DELETE /automationtemplates/{key}

GET /automationtemplates/{key}/renderdraft/{contactID}

GET /automationtemplates/{key}/renderpublished/{contactID}

API Description and Functional Purpose:

An automationtemplate instance within the automationtemplates collection contains the essential information to define a communication template for an automated message. Templates include details for content, channel, classification of communication (transactional or promotional), subject line, from and reply address, and HTML. It is possible to use a template one or more times.

Additional information:

Template key values must be unique. Therefore, it is important to consider a naming convention that will accommodate creating multiple templates over time. For example. "sports_newsletter_Jan_2018_week1" is better than "jan_newsletter".

Cordial provides a default transport for sending communications; however it is possible to use an external provider if needed.

By default, results data is aggregated on a "daily" interval. This can be optionally set to "hourly" if further granularity is needed.

POST /automationtemplates

Method

URI Path

POST

/automationtemplates

Creates a new message template in the Cordial database using the appropriate JSON body.

Posting more than one time for the same template key value will generate an error. Use PUT to change or update template data once created.

Parameters

*Required

Parameter

Type

Description

Example

Template

*key

string

Unique value assigned to the template. The key may only contain letters, numbers, and dashes.

news-01-21-2018

*Name

string

A name given to the message.

news-01-21-2018

*channel

string

Description of the channel for this template.

email

*classification

string

Describes the class of communication. Options include transactional and promotional.

transactional

*baseAggregation

string

Specific to API and triggered messages. Options include daily and hourly.

daily

transportID

string

Defines the transported if overriding the default.

trans_1134

draftContent

string

Defines if the message will be submitted as a draft or published version. Value is boolean: true or false. Default is false.

true

trackLinks

string

Enables or disables storing link tracking data. Options include or enabled or disabled. The default is enabled.

disabled

Message/Headers

*subject

string

The subject line for the communication.

Welcome!

*fromEmail

string

The email address that the message is from.

[email protected]

*fromDesc

string

Describes who is the sender.

CS Dept

*replyEmail

string

The email address that the message's replies will go to.

[email protected]

Message/Content

*text/html

string

HTML markup for the message.

<div>content</div>

Example JSON Requests

The following will create a new automation template for a promotional email.

{

"key": "promo_01_20_2018",

"name": "promo_01_20_2018",

"channel": "email",

"classification": "promotional",

"baseAggregation": "hourly",

"message": {

"headers": {

"subject": "One Day Only Sale",

"fromEmail": "[email protected]",

"replyEmail": "[email protected]",

"fromDesc": "Promotions Team"

},

"content": {

"text/html": "<div>Hello World</div>"

}

}

}

Example Request URIs

The following URI in conjunction with the JSON will perform the POST of the automationtemplates.

http://<path>/automationtemplates

GET /automationtemplates

Method

URI Path

GET

/automationtemplates

Retrieves all automation templates from the Cordial database.

Query String Parameters

Parameter

Type

Description

Example

fields

string

Limits the data returned to the fields specified. Multiple fields are comma separated.

Possible Values:

key, name, classification, channel, stats, baseAggregation, status, createdAt, lastUpdate, message, mdtID

?fields=key\%2ClastUpdate

ct[gt]

string

Returns records where the create date is greater than the specified date.

?ct\%5Bgt\%5D=2018-01-01T00:00:00.000Z

ct[gte]

string

Returns records where the create date is greater than or equal to the specified date.

?ct\%5Bgte\%5D=2018-01-01T00:00:00.000Z

ct[lt]

string

Returns records where the create date is less than the specified date.

?ct\%5Blt\%5D=2018-01-01T00:00:00.000Z

ct[lte]

string

Returns records where the create date is less than or equal to the specified date.

?ct\%5Blte\%5D=2018-01-01T00:00:00.000Z

lm[gt]

string

Returns records where the last modified time is greater than the specified date.

?lm\%5Bgt\%5D=2018-01-01T00:00:00.000Z

lm[gte]

string

Returns records where the last modified time is greater than or equal to the specified date.

?lm\%5Bgte\%5D=2018-01-01T00:00:00.000Z

lm[lt]

string

Returns records where the last modified time is less than the specified date.

?lm\%5Blt\%5D=2018-01-01T00:00:00.000Z

lm[lte]

string

Returns records where the last modified time is less than or equal to the specified date.

?lm\%5Blte\%5D=2018-01-01T00:00:00.000Z

tags

string

Returns results that contain the specified message tags. Multiple tags are comma separated.

?tags=welcome\%2C\%20promo

page

string

Specifies the results page number.

?page=3

per_page

string

Specifies the number of records returned per page.

?per_page=100

Example Request URIs

The following URI will retrieve all automation templates and include all fields.

http://<path>/automationtemplates

The following URI will retrieve all automation templates, but will only include the field data for "name".

http://<path>/automationtemplates?fields=name

The following URI will retrieve all automation templates, and will only include the field data for "name" and "message".

http://<path>/automationtemplates?fields=name\%2Cmessage

The following URI will retrieve all automation templates starting from the third page grouping contacts by 10. For example, page-1 would have included the first 10, page-2 the second group of 10 and so on.

http://<path>/automationtemplates?page=3&per_page=10

GET /automationtemplates/{key}

Method

URI Path

GET

/automationtemplates/{key}

Retrieves an automation template from the Cordial database.

The automation template record is defined by the template's unique key value.

Query String Parameters

Parameter

Type

Description

Example

fields

string

Limits the data returned to the fields specified. Multiple fields are comma separated.

Possible Values:

key, name, classification, channel, stats, baseAggregation, status, createdAt, lastUpdate, message, mdtID

?fields=key\%2ClastUpdate

Example Request URIs

The following URI will retrieve an automation template where the key value is "promo_01_20_2018" and include all fields.

http://<path>/automationtemplates/promo_01_20_2018

The following URI will retrieve an automation template where the key value is "promo_01_20_2018", but will only include the field data for name.

http://<path>/automationtemplates/promo_01_20_2018?fields=name

The following URI will retrieve an automation template where the key value is "promo_01_20_2018", and will only include the field data for name and message.

http://<path>/automationtemplates/promo_01_20_2018?fields=name\%2Cmessage

PUT /automationtemplates/{key}

Method

URI Path

PUT

/automationtemplates/{key}

Updates fields for a automation template within the Cordial database.

The automation template record is defined by the template's unique key value.

For example, /automationtemplates/promo_01_20_2018 allows the template with the key value of "promo_01_20_2018" to be updated using the appropriate JSON body.

Parameters

*Required

Parameter

Type

Description

Example

Template

transportID

string

Defines the transported if overriding the default.

trans_1134

draftContent

string

Defines if the message will be submitted as a draft or published version. Value is boolean: true or false. Default is false.

true

trackLinks

string

Enables or disables storing link tracking data. Options include or enabled or disabled. The default is enabled.

disabled

Message/Headers

*subject

string

The subject line for the communication.

Welcome!

*fromEmail

string

The email address that the message is from.

[email protected]

*fromDesc

string

Describes who is the sender.

CS Dept

*replyEmail

string

The email address that the message's replies will go to.

[email protected]

Message/Content

text/html

string

HTML markup for the message.

<div>content</div>

Example JSON Requests

The following will update the subject for an automation template.

{

"message": {

"headers": {

"subject": "Big Sale This Weekend",

"fromEmail": "[email protected]",

"replyEmail": "[email protected]",

"fromDesc": "Promo Team"

}

}

}

Example Request URIs

The following URI in conjunction with the JSON will perform the PUT to the automation template "promo_01_20_2018".

http://<path>/automationtemplates/promo_01_20_2018

POST /automationtemplates/{key}/publish

Method

URI Path

POST

/automationtemplates/{key}/publish

Publishes an automation template draft.

The automation template record is defined by the template's unique key value.

Example Request URI

The following URI will perform a POST to the automation template with a key of "promo_01_20_2018 ".

http://<path>/automationtemplates/promo_01_20_2018/publish

POST /automationtemplates/{key}/senddraft

Method

URI Path

POST

/automationtemplates/{key}/senddraft

Sends an automation template draft for testing purposes.

The automation template draft to be sent is defined by the template's unique key value.

For example, /automationtemplates/promo_01_20_2018/senddraft allows the template with the key value of "promo_01_20_2018" to be sent using the appropriate JSON body.

The template can be sent to one or more contacts, as defined within the JSON body.

Parameters

*Required

Parameter

Type

Description

Example

To/Contact

*contact identifier

string

Specify the message recipient using a contact identifier value.

[email protected], ID1234, 16198880000

Using extVars, any number of additional external variables may be added. These values are then available in the template. For example, if "extVars": {"orderID": "o1234"} is included as an order ID value, then in the message it can be accessed as {$extVars.orderID}.

Note: Data passed within external variables is not stored in the Cordial platform.

Example JSON Requests

The following will send a message to a single contact. The three examples each use a different contact identifier key/value pair to identify the recipient.

Email as Identifier

cID as Identifier

Custom Identifier

{

"to": {

"contact": {

"email": "[email protected]"

},

"extVars": {

"orderID": "123",

"orderItems": [

{

"name": "Tour Tee",

"amount": "22.50"

},

{

"name": "Icon Tee",

"amount": "25.50"

},

{

"name": "Icon Hat",

"amount": "15.50"

}

]

}

}

}

{

"to": {

"contact": {

"cID": "58d30719ac0c8117814da1f3"

},

"extVars": {

"orderID": "123",

"orderItems": [

{

"name": "Tour Tee",

"amount": "22.50"

},

{

"name": "Icon Tee",

"amount": "25.50"

},

{

"name": "Icon Hat",

"amount": "15.50"

}

]

}

}

}

{

"to": {

"contact": {

"customKey": "identifierValue"

},

"extVars": {

"orderID": "123",

"orderItems": [

{

"name": "Tour Tee",

"amount": "22.50"

},

{

"name": "Icon Tee",

"amount": "25.50"

},

{

"name": "Icon Hat",

"amount": "15.50"

}

]

}

}

}

POST /automationtemplates/{key}/send

Method

URI Path

POST

/automationtemplates/{key}/send

Sends an automation template.

The automation template to be sent is defined by the template's unique key value.

For example, /automationtemplates/promo_01_20_2018 week1/send allows the template with the key value of "promo_01_20_2018" to be sent using the appropriate JSON body.

The template can be sent to one or more contacts, as defined within the JSON body.

Note: This endpoint will successfully create a new contact record if the contact identifier value in the request does not already exist. The newly added contact will have a subscribe status of none and will not receive promotional messages until subscribed to the appropriate channel.

Note: There is a 1 request per second default limit on API send calls. Additional capacity can be requested by contacting your Client Success Manager.

Parameters

*Required

Parameter

Type

Description

Example

To/Contact

*contact identifier

string

Specify the message recipient using a contact identifier value.

[email protected], ID1234, 16198880000

identifyBy

string

Denotes the identifier key to be used to look up the contact.

email, cID, customKey

The identifyBy parameter is used to specify which identifier key in the request body should be used to look up the contact. Because contact attribute data sent in the "contact" object of the call will upsert corresponding contact attributes in the Cordial platform, identifyBy should be used to specify which key is the identifier. The use of this parameter becomes especially relevant for Cordial accounts where a contact can be uniquely identified using more than one identifier key.

Note: For calls where identifyBy is not included, the request body will be searched for the key that serves as the primary contact identifier in your Cordial account, and if not found, the call will return the pk-not-preset-inpayload response.

Using extVars, any number of additional external variables may be added. These values are then available in the template. For example, if "extVars": {"orderID": "o1234"} is included as an order ID value, then in the message it can be accessed as {$extVars.orderID}.

Note: Data passed within external variables is not stored in the Cordial platform.

Example JSON Requests

The following will send to a single contact.

Email as Identifier

cID as Identifier

Custom Identifier

{

"identifyBy": "email",

"to": {

"contact": {

"email": "[email protected]"

},

"extVars": {

"orderID": "123",

"orderItems": [

{

"name": "Tour Tee",

"amount": "22.50"

},

{

"name": "Icon Tee",

"amount": "25.50"

},

{

"name": "Icon Hat",

"amount": "15.50"

}

]

}

}

}

{

"identifyBy": "cID",

"to": {

"contact": {

"cID": "58d30719ac0c8117814da1f3"

},

"extVars": {

"orderID": "123",

"orderItems": [

{

"name": "Tour Tee",

"amount": "22.50"

},

{

"name": "Icon Tee",

"amount": "25.50"

},

{

"name": "Icon Hat",

"amount": "15.50"

}

]

}

}

}

{

"identifyBy": "customKey",

"to": {

"contact": {

"customKey": "identifierValue"

},

"extVars": {

"orderID": "123",

"orderItems": [

{

"name": "Tour Tee",

"amount": "22.50"

},

{

"name": "Icon Tee",

"amount": "25.50"

},

{

"name": "Icon Hat",

"amount": "15.50"

}

]

}

}

}

The following will send to multiple email addresses.

{

"identifyBy":"email",

"to":

[

{

"contact": {

"email": "[email protected]"

},

"extVars": {

"orderID": "123",

"orderItems": [

{

"name": "Tour Tee",

"amount": "22.50"

},

{

"name": "Icon Tee",

"amount": "25.50"

},

{

"name": "Icon Hat",

"amount": "15.50"

}

]

}

},

{

"contact": {

"email": "[email protected]"

},

"extVars": {

"orderID": "456",

"orderItems": [

{

"name": "San Diego Tee",

"amount": "22.75"

},

{

"name": "Icon Tee",

"amount": "25.50"

},

{

"name": "Winter Hat",

"amount": "13.40"

}

]

}

}

]

}

The following will send to a single email address AND will set the contact subscribe status to subscribed. Note the channels addition to the JSON.

{

"identifyBy":"email",

"to": {

"contact": {

"channels": {

"email": {

"address": "[email protected]",

"subscribeStatus": "subscribed"

}

},

"fname": "mark"

},

"extVars": {

"orderID": "123",

"orderItems": [{

"name": "Tour Tee",

"amount": "22.50"

}, {

"name": "Icon Tee",

"amount": "25.50"

}, {

"name": "Icon Hat",

"amount": "15.50"

}]

}

}

}

Error Response Messages

Action

Error Message

ResponseCode

Attempt to send an automated template to a malformed email address or the contact identifier key is uniquely constrained to an existing contact record.

validation

201

Attempt to send a promotional message to a contact who is not subscribed or attempt to send to a contact that does not have an email address in the system.

Contact not subscribed

201

Pass in a parameter in the api call that is not part of the payload schema.

Key (key name provided) is not part of the schema for this resource.

422

Both templateID and key are part of the payload.

Specify only one of "key" or "templateID.

422

Attempt to send to an automated template that is not published.

There is no published version for this template.

422

"To" parameter is not part of payload.

"to" must be specified

422

Attempt to send automated template that does not have API sending enabled.

Trigger API is disabled

422

Attempt to send an automated template where the "to" parameter does not contain a single contact or an array of contacts.

"to" parameter must contain a single contact or an array of contacts to send to

422

Attempt to send an automated template to an array of contacts and one of the entries does not contain a value.

contact-data-not-found

422

Attempt to send to same contact more than once per millisecond.

exceeded-rate-limit

422

Cordial is unable to create message contact record.

internal-error

422

Attempt to send an automated template that does not exist.

an error has occurred

500

DELETE /automationtemplates/{key}

Method

URI Path

DELETE

/automationtemplates/{key}

Deletes an automation template within the Cordial database.

The automation template is defined by the template's unique key value.

For example, /automationtemplate/sports_newsletter_Jan_2018_week1 would delete the template with the key value of "sports_newsletter_Jan_2018_week1".

Example Request URIs

The following URI will delete an automation template where the key value is "promo_01_20_2018".

http://<path>/automationtemplates/promo_01_20_2018

GET /automationtemplates/{key}/renderdraft/{contactID}

Method

URI Path

GET

/automationtemplates/{key}/renderdraft/{contactID}

Retrieves the message headers, the rendered HTML and experiment name and variants of an automated template draft for a specified contact.

The automation template is defined by the template's unique key value.

The contact record is defined by the contact's unique "cID" value.

For example, /automationtemplates/order_confirm/renderdraft/58d30719ac0c8117814da1f3" will return the response data of the draft template with the key value of "order_confirm" and the contactID of "58d30719ac0c8117814da1f3".

Additionally, you can pass experiment names and variants using a query string.

Query String Parameters

Parameter

Type

Description

Example

experiment

string

Returns the automation template populated with the specified experiment. Variant is required if experiment is specified.

?experiment=SubjectTest&variant=Left_Cart_Items

variant

string

Returns the automation template populated with the specified experiement variant. Experiement is required if variant is specified.

?experiment=SubjectTest&variant=Left_Cart_Items

Example Request URIs

The following URI will perform the GET to the automation template draft where:

Key = order_confirm

Contact ID = 58d30719ac0c8117814da1f3

http://<path>/automationtemplates/order_confirm/renderdraft/58d30719ac0c8117814da1f3

The following URI will perform the GET to the automation template draft where:

Key = order_confirm

Contact ID = 58d30719ac0c8117814da1f3

Subject experiment = SubjectTest

Subject experiment Variant = TestSubjectA

http://<path>/automationtemplates/order_confirm/renderdraft/58d30719ac0c8117814da1f3?experiment=SubjectTest&variant=TestSubjectA

The following URI will perform the GET to the automation template draft where:

Key = order_confirm

Contact ID = 58d30719ac0c8117814da1f3

Subject experiment = SubjectTest

Subject experiment Variant = TestSubjectA

Body experiment = BodyExperiment

Body experiment variant = BodyA

http://<path>/automationtemplates/order_confirm/renderdraft/58d30719ac0c8117814da1f3?experiment=SubjectTest&variant=TestSubjectA&experiment=BodyExperiment&variant=BodyA

GET /automationtemplates/{key}/renderpublished/{contactID}

Method

URI Path

GET

/automationtemplates/{key}/renderpublished/{contactID}

Retrieves the message headers, the rendered HTML and experiment name and variants of a published automated template for a specified contact.

The automation template is defined by the template's unique key value.

The contact record is defined by the contact's unique "cID" value.

For example, /automationtemplates/order_confirm/renderpublished/58d30719ac0c8117814da1f3" will return the response data of the published template with the key value of "order_confirm" and the contactID of "58d30719ac0c8117814da1f3".

Additionally, you can pass experiment names and variants using a query string.

Query String Parameters

Parameter

Type

Description

Example

experiment

string

Returns the automation template populated with the specified experiment. Variant is required if experiment is specified.

?experiment=SubjectTest&variant=Left_Cart_Items

variant

string

Returns the automation template populated with the specified experiement variant. Experiement is required if variant is specified.

?experiment=SubjectTest&variant=Left_Cart_Items

Example Request URIs

The following URI will perform the GET to the published automation template where:

Key = order_confirm

Contact ID = 58d30719ac0c8117814da1f3

http://<path>/automationtemplates/order_confirm/renderpublished/58d30719ac0c8117814da1f3

The following URI will perform the GET to the published automation template where:

Key = order_confirm

Contact ID = 58d30719ac0c8117814da1f3

Subject experiment = SubjectTest

Subject experiment Variant = TestSubjectA

http://<path>/automationtemplates/order_confirm/renderpublished/58d30719ac0c8117814da1f3?experiment=SubjectTest&variant=TestSubjectA

The following URI will perform the GET to the published automation template where:

Key = order_confirm

Contact ID = 58d30719ac0c8117814da1f3

Subject experiment = SubjectTest

Subject experiment Variant = TestSubjectA

Body experiment = BodyExperiment

Body experiment variant = BodyA

http://<path>/automationtemplates/order_confirm/renderpublished/58d30719ac0c8117814da1f3?experiment=SubjectTest&variant=TestSubjectA&experiment=BodyExperiment&variant=BodyA

In this Article

Welcome Message Overview

Implementing the Trigger

Creating the Automated Message

Overview

A welcome message is an automated message that is sent when a customer signs up for your email list, newsletter, loyalty or rewards program. The message can be configured so that it is sent to a contact once they perform a particular action such as submitting a form or clicking a button on your site.

The welcome message is an important initial communication between you and your customer. It should set expectations about the valueand cadenceof the communications they will be receiving. The welcome message strategy can be a single message or a series of messages.

Implementing the Trigger

In order for a welcome message to send, there needs to be data sent to the system that will trigger the automation. In the following example, we will trigger a welcome message when a contact is added to a list. Learn more about how to create list attributes.

There are 2 implementations you can use to send the data to Cordial:

JavaScript listener implementation - JavaScript code placed on your website that sends data to Cordial from the client side browser. Learn more about setting up the core JavaScript code.

Rest API implementation - a server side alternative to javaScript that sends data to Cordial via the API. Learn about updating contact records via the API.

This strategy utilizes 1primary piece of data.

List attribute

Purpose: Used to flag a contact as "in" or "out" of a specific segment, newsletter subscription, loyalty program, rewards program or interest group. It's recommended to enable "Date Tracking" for the list. This setting tells the system to record the date a contact is added.

Data type: A list is a type of contact attribute. This value is passed as a boolean true/false value.

JavaScript Listener Implementation

The following function should be executed when a customer provides their email address and expresses interest in receiving promotional messages via a form or checkout process.

cordial.identify(emailaddress);

cordial.contact({

"$list_name": true,

"channels": {"email": {"subscribeStatus": "subscribed"}}

});

The cordial.identify function sets the appropriate cookie and the cordial.contact function adds or updates a contact record. The $list_name should be replaced with the name of the list that you create.

Full details on the cordial.contact method.

REST API Implementation (server-side alternative to javaScript)

Note: The REST API Implementation is an alternative method to the Embedded JavaScript Listener. This is a server-side approach to sending the data to Cordial.

Method to call when subscribing a contact to a list:

POST <path>/contacts (adds a new contact record or updates an existing contact record)

{

"channels": {

"email": {

"address": "$email_address",

"subscribeStatus": "subscribed"

}

},

"$list_name": true

}

Creating the Automated Message

Now that we have the appropriate data (passed by either the js listener or the REST API) we can set up the event triggered automation template.

In the navigation menu choose "Message Automation" and click "Create New Automation".

In the left panel under "Sending Method", click "Event Triggered"

learn how to set up a welcome series

For "Trigger event", choose "When a contact is added to a list" and select the name of the list you would like to target.

For "Delivery Time" choose "Send Immediately". You have the option to delay the message, but in most cases an immediate response is appropriate.

For "How often can this message be sent to an individual" select "Once only".

Save the trigger setting.

Once this is saved and the message content is published you can "Enable" the message. As soon as a message is enabled the triggers are active and will send the message according to the rules applied.

In the next article.

API Set Name: contactimports

POST /contactimports

API Description and Functional Purpose:

The contactimports resource creates an import job to batch load a file of contacts into the Cordial database from an external location.

Additional information:

This resource uses the JSON request information to define the host location of the data file, the transport protocol and the host login authentication information.

It is important to note that this resource is not a collection of imports, but is a resource that initiates import processing by creating an import job.

Import status information is available through the jobs resource using the returned jobID.

Data file information:

Permissible import file types include CSV, TSV, TXT.

Column headers need to be the key value for contact attributes, and the name or ID value for account lists.

Import files will be stored for 30 days from the date of the import. This does not impact the data that was uploaded.

The file is broken up into several files and imported simultaneously to lessen the total import time. File order is not preserved in this case.

First row column headers must describe the data for that column.

Parameters

* Required

Column Headers

Description

Expected values

*channels.email.address

Contact email address.

Valid email address

contact attribute key

The contact attribute key value.

string, date (ISO 8601), number

list name or ID

The list assignment of the contact, true (1) or false (0).

1, 0 (boolean)

channels.email.subscribeStatus

Contact subscribe status. Note that subscribe status is set to "subscribed" by default if no value is passed. To ensure subscribe status is unchanged when updating existing contacts, set thesubscribe parameter in the API call to "false".

subscribed, unsubscribed, none

Example CSV

channels.email.address,channels.email.subscribeStatus,ex_stng,ex_num,ex_date,fr_name,Ex-List

[email protected],subscribed,test1,1,2/1/1970,Chris,1

[email protected],subscribed,test2,1,2015-04-21,Ted,1

[email protected],subscribed,test3,2,2/2/2015,Frank,1

[email protected],subscribed,test4,2,2015-01-19,Tom,1

[email protected],subscribed,test5,3,1997-02-17T05:21:41+00:00,Tony,1

[email protected],subscribed,test6,3,2015-02-05T02:05:17+00:00,Mike,0

Resource Associations:

The following resource collections are associated to this collection.

Collection

Association

contacts

The contactimports resource creates contact documents/records in the contacts collection/resource.

Jobs

The contactimports resource creates job documents/records in the jobs collection/resource.

POST /contactimports

Method

URI Path

POST

/contactimports

Creates an import job using the JSON body information.

Parameters

* Required

Parameter

Type

Description

Example

job

importName

string

Names of the import job. May only contain letters, numbers and dashed. Does not accept whitespaces.

ContactImport-7-31

importDescription

string

Briefly describe the import job. The description will appear on the jobs page in Cordial.

July summer sale participants.

confirmEmail

email

Email address to send an administrative alert that the import job has been completed.

[email protected]

hasHeader

(required if columns is not included)

boolean

Denotes the first row column headers are present, default is false

true

columns

(required if hasHeader is not explicitly set to true)

array

Array of column headers, ordered by column positionally left to right, using "" will ignore the entire column

["channels.email.address", " channels.email. subscribeStatus", "first"]

delimiter

string

Character used to break up columns in file. The default is "," if not provided.

|

strategy

updateOnly or insertOnly

Insert only - only adds new records. updateOnly will only update existing records. If undefined the import will insert and update. The default is undefined.

insertOnly

suppressTriggers

boolean

If true, will suppress any triggered messages set to fire based on updates to values in the import. Defaults to true.

false

forceSubscribe

boolean

If set to true, will allow previously unsubscribed contacts to be updated as subscribed. Defaults to false.

false

subscribe

boolean

If set to false, will not change current contact subscribeStatus. Defaults to true and will subscribe new contacts and contacts with subscribeStatus of none.

true

nullMarker

string

Defines the value to use for ignoring or skipping attribute updates.

Upon import, if an attribute contains the nullMarker value (i.e. ignore), then the attribute will be skipped or ignored. See example below.

ignore

*source

object

See parameters for source below.

"source":{}

lists

object

See parameters for lists below.

"lists":{}

source

*transport

string

Defines the transport method

Possible Values:

HTTP, HTTPS, FTP, SFTP, S3, GCS (Google Cloud Storage)

https

url

(required if transport = HTTP or HTTPS)

url

URL or location of the import file.

http://files.example.com/file.csv

port

(required if transport = FTP or SFTP, and not using default)

string

The port number for the server.

44

server

(required if if transport = FTP or SFTP)

string

domain

example.com

username

(required if if transport = FTP or SFTP)

string

An account username for gaining access to the file location.

myusername

password

(required if if transport = FTP or SFTP)

string

The account password for the above user name.

Msm1th$99!

path

(if transport = FTP, SFTP or S3, or GCS)

string

optional directory path to the file

/folder/file.csv

aws_access_key_id

(required if transport = S3)

string

public aws id

erg45g45hsdh

aws_secret_access_key

(required if transport = S3)

string

secret aws key

dudhKDDHE476383kdsdhdk

aws_bucket

(required if transport = S3)

aws bucket name

some-bucket

aws_region

(required if transport = S3)

string

aws region

us-west-2

bucket

(required if transport = GCS)

string

Defines the bucket name if transport is Google Cloud Storage. Be sure to use the same name from the setup process in Cordial marketplace.

name_used_in_marketplace_setup

list

addTo

(required if list parameter passed)

array

All Contacts will get added to each list in the array. If you pass this parameter, you should not pass a column in the file with the same key. This field will always win.

["foo","bar"]

removeFrom

(required if list parameter passed)

array

All Contacts will get removed from each list in the array. If you pass this parameter, you should not pass a column in the file with the same key. This field will always win.

["biz","baz"]

Note: if the CVS file has both "1" (true) and "0" (false) values for each contact for list "foo", and the request contains a lists object with instructions toadd all contacts to "foo", then ALL contacts will be added to "foo" irrespective of the boolean values in the files column. In other words, the lists object in the request will overrule the values set in the file itself.

Note: Regardless of strategy, if a contact in the database has a subscribe status of "none" and no value is passed for channels.email.subscribeStatus in the import file, then the subscribe status will be updated to "subscribed". To prevent a contact's subscribe status from being automatically updated, set the subscribe parameter in the JSON body to "false".

Note: It is necessary to pass the forceSubscribe parameter with a value of "true" in order to resubscribe contacts who have previously unsubscribed. If this parameter is missing a previously unsubscribed contact will not be subscribed even if the import file contains a column for channels.email.subscribeStatus.

Example JSON Request for HTTP or HTTPS

The following will initiate an import job to load a CSV file from a secure HTTP location. A confirmation email will be sent to the email address provided once the job is complete. The JSON response will provide a job ID for checking job status if needed.

{

"source":{

"transport":"https",

"url":"https://files.example.com/new_data.csv"

},

"columns":[

"channels.email.address",

"channels.email.subscribeStatus",

"first"

],

"confirmEmail":"[email protected]"

}

Example JSON Request for FTP or SFTP

The following will initiate an import job to load a CSV file via a secure FTP connection on port 44 (not the default). A confirmation email will be sent to the provided email address once the job is complete. The JSON response will return a job ID for checking job status if needed.

{

"source":{

"transport":"sftp",

"port":"44",

"server":"example.com",

"username":"myusername",

"password":"Msm1th$99!",

"path":"/files/file.csv"

},

"hasHeader":true,

"confirmEmail":"[email protected]"

}

Example JSON Request for S3

The following will initiate an import job to load a CSV file via a secure S3 connection. A confirmation email will be sent to the provided email address once the job is complete. The JSON response will return a job ID for checking job status if needed.

{

"source":{

"transport":"s3",

"aws_access_key_id":"AAAAAAAAAAAAAAAAAAAA",

"aws_secret_access_key":"dudhKDDHE476383kdsdhdkasKDHDKDeiuealskjD",

"aws_bucket":"a-bucket",

"aws_region":"us-west-2",

"path":"folder/contacts.csv"

},

"hasHeader":true,

"confirmEmail":"[email protected]"

}

Example JSON Request for Google Cloud Storage

The following will initiate an import job to load a CSV file via a secure GCS connection. A confirmation email will be sent to the provided email address once the job is complete. The JSON response will return a job ID for checking job status if needed.

{

"source":{

"transport":"gcs",

"bucket":"same_name_used_in_marketplace_setup",

"path":"/folder/file.csv"

},

"hasHeader":true,

"confirmEmail":"[email protected]"

}

Example Request URIs

The following URI in conjunction with the JSON will perform the POST.

http://<path>/contactimports

Lists

Add or remove all contacts from a list or lists

See the example below. The "lists" object will add all contacts in the imported file to lists "foo" and "bar". It will also remove all contacts in the imported file from the list "biz".

{

"source":{

"transport":"https",

"url":"https://files.example.com/new_data.csv"

},

"columns":[

"channels.email.address",

"channels.email.subscribeStatus",

"first"

],

"confirmEmail":"[email protected]",

"delimiter":"|",

"lists":{

"addTo":[

"foo",

"bar"

],

"removeFrom":[

"biz"

]

}

}

Note: If the CVS file has both "1" (true) and "0" (false) values for each contact for list "foo", and the request contains a "lists" object with instructions toadd all contacts to "foo", then ALL contacts will be added to "foo" irrespective of the boolean values in the files column. In other words, the "lists" object in the request will overrule the values set in the file itself.

Examples of how updates are handled

When updating a contact record:

If providing an attribute key with a value, the attribute will be updated with the new value in the database.

If providing an attribute key with an empty string, the attribute will be updated with the empty string in the database.

If providing an attribute key with a nullMarker value, the attribute will be skipped and not updated in the database.

If an attribute key is not provided, the attribute will be skipped and not updated in the database.

Note in the CSV example below:

The first_name attribute with the value "Bill" will update the attribute in the database to "Bill".

The pet_name attribute with the defined nullMarker value "ignore" will ignore updating the attribute and leave it as "Sparky" in the database.

The pet_breed attribute with an empty string value will update the attribute in the database to an empty string.

Example contact record before import

{

"channels":{

"email":{

"address":"[email protected]"

}

},

"first_name":"Fred",

"pet_name":"Sparky",

"pet_breed":"Poodle"

}

Example CSV to be imported

Note in this example, the nullMarker parameter value was defined as "ignore".

"channels.email.address","first_name","pet_name","pet_breed"

"[email protected]","Bill","ignore",""

Example contact record after import

{

"channels":{

"email":{

"address":"[email protected]"

}

},

"first_name":"Bill",

"pet_name":"Sparky",

"pet_breed":""

}

API Set Name:accountlists

POST /accountlists

GET /accountlists

GET /accountlists/{id}

PUT /accountlists/{id}

PUT /accountlists/{id}/clear

DELETE /accountlists/{id}

API Description and Functional Purpose:

The accountlists collection contains names of lists used to define segments of your audience. For example, you may have lists for "Weekly Specials", "Daily Deals" and "Fashion Newsletter". Each represents subscriber selections on information and promotions they requested to receive. You may also use accountlists to represent groups or segments you determine to be important such as "New Customers", "VIPs" or "Net Promoters".

Additional information:

A contact can be associated with one or more lists.

There is no limit to how many lists can be created.

List names are required to be unique, so it is important to use a naming convention that supports the creation of multiple lists over time.

Resource Associations:

The following resource collections are associated to this collection.

Collection

Association

contacts

Contacts can be associated to accountlists, identifying a contact as a member of one or more account lists.

POST /accountlists

Method

URI Path

POST

/accountlists

Creates a new account list in the Cordial database using the appropriate JSON body.

Posting more than one time for the same list name will generate an error.

Parameters

*Required

Parameter

Type

Description

Example

*name

string

Unique name to identify and reference the list

safe-drivers

Example JSON Requests

The following will create a new accountlistnamed "safe_drivers". Note that list names must be unique.

{

"name": "safe_drivers"

}

Example Request URIs

The following URI in conjunction with the JSON will perform the POST.

http://<path>/accountlists

GET /accountlists

Method

URI Path

GET

/accountlists

Retrieves all account lists from the Cordial database.

Using a query string parameter, it is also possible to filter the response by list "name" to retrieve information for a single list.

Example Request URIs

The following URI will retrieve all accountlists.

http://<path>/accountlists

The following URI will retrieve an accountlist where the list name is "safe_drivers".

http://<path>/accountlists?name=safe_drivers

GET /accountlists/{id}

Method

URI Path

GET

/accountlists/{id}

Retrieves an account list from the Cordial database.

The accountlist is defined by the accountlist's unique "id" value.

For example, /accountlists/vip would return the response data for the list with the id value of "vip".

Example Request URIs

The following URI will retrieve an accountlist where the id value is "128". Note that when a list is created, an "id" value is generated uniquely for that list.

http://<path>/accountlists/128

PUT /accountlists/{id}

Method

URI Path

PUT

/accountlists/{id}

Updates the list name to a new value and enables or disables date tracking.

Parameters

*Required

Parameter

Type

Description

Example

*id

number

Unique list id to identify and reference the list.

128

*name

string

Updated list name to replace the existing value.

vip_guests

enhanced

boolean

Enable or disable date tracking when contacts are added to the list.

true, false

Example JSON Requests

The following will update the existing accountlist name "guests" to "vip_guests" and enable date tracking.

{

"id": 128,

"name": "vip_guests",

"enhanced": true

}

Example Request URIs

The following URI in conjunction with the JSON will perform the PUT.

http://<path>/accountlists/128

PUT /accountlists/{id}/clear

Method

URI Path

PUT

/accountlists/{id}/clear

Removes all contact list association while retaining the list itself in the Cordial database.

Example Request URIs

The following URI will clear all contacts from an accountlist where the id value is "128". Note that when a list is cleared, no contacts will be deleted from the system.

http://<path>/accountlists/128/clear

DELETE /accountlists/{id}

Method

URI Path

DELETE

/accountlists/{id}

Deletes an account list within the Cordial database.

The accountlist is defined by the accountlist's unique "id" value.

For example, /accountlists/128 would delete the list with the id value of "128".

Example Request URIs

The following URI will delete an accountlist where the id value is "128". Note that when a list is created, an "id" value is generated uniquely for that list.

http://<path>/accountlists/128

Table of Contents

Overview

Installation

crdl(contact) - Adding and Updating a Contact

crdl(event) - Tracking Custom Events

crdl(cartitem) - Updating Cart Items

crdl(order) - Adding Orders

crdl(param-store) - Storing Parameters

crdl(forget) - Clearing Cookies

Overview

Using the available JavaScript methods you are able to:

Add and update contacts to the contacts collection.

Add custom events to the contact activities collection.

Add cart items to the cart object of the contacts collection.

Add orders to the orders collection.

Each browser is assigned a unique browser ID (BID). Multiple BID's can be associated with a contact, depending on their browsing activity. This makes it possible to identify a user across different browsers and domains.

If a contact arrives on your site from a tracked link, third-party cookies will be set to identify the contact.

If the user has not arrived from a tracked link, the user can be added or updated using the crdl('contact') method.

If there is no referring message or known contact identifier available, an anonymous BID will be assigned to the session user.

All activity ( orders, cart, events ) will be tracked for 30 days and attributed to the anonymous BID. In the event that a contact identifier becomes available for the anonymous user, activity thereafter will be tracked and attributed to the known contact, and previously generated activity from their anonymous session will be copied into their contact record.

Tip: Event activity belonging to anonymous users cannot be viewed in the Cordial platform until the user's record is created through identification.

Note: Due to data privacy compliance (i.e. GDPR ), certain functionality of adding and editing contacts via JavaScript requires explicit consent and additional setup. Please contact your Client Success Manager or submit a support request for more info.

Note: The manner in which track script stores and uses cookies may change from time to time, without notice, to accommodate changes to Cordial products and services, and in response to new technologies and industry practices.

Installation

Include the following base script before the closing body tag of the page or site template:

<script>

(function(C,O,R,D,I,A,L){

C.CordialObject=I,C[I]=C[I]||function(){(C[I].q=C[I].q||[]).push(arguments)};

C[I].l=1*new Date,C[I].q=[],A=O.createElement(R);

L=O.getElementsByTagName(R)[0],A.async=1,A.src=D,L.parentNode.insertBefore(A,L);

})(window, document, 'script', '//track.cordial.io/track.v2.js', 'crdl');

crdl('connect', 'YOUR_ACCOUNT_KEY_HERE', {

trackUrl: "//track.cordial.io",

connectUrl: "//track.cordial.io",

cookieDomain: "cordial.io",

cookieLife: 365

});

</script>

Setting the accountKey

Replace the YOUR_ACCOUNT_KEY_HERE with your Cordial account key.

Your Cordial account key can be found in the application under your username (top right)> Account Settings > Account Info panel.

Setting the config

crdl('connect', YOUR_ACCOUNT_KEY_HERE, {config});

You are able to override the following default configurations:

Parameter

Type

Description

Default

trackUrl

string

The Cordial endpoint that track calls will be sent to (only special situations may require a change, e.g. a custom domain).

track.cordial.io

connectUrl

string

The endpoint for connecting with Cordial cookies (only special situations may require a change, e.g. a custom domain).

track.cordial.io

cookieDomain

string

Sets which domain cookie will get stored. (only special situations may require a change, e.g. a custom domain).

cordial.io

cookieLife

integer

Expiration of cookie in days, default is 365 days.

365

crdl('connect', 'cordial', {

trackUrl: "//track.cordial.io",

connectUrl: "//track.cordial.io",

cookieDomain: "cordial.io",

cookieLife: 365

});

crdl(contact) - Adding and Updating a Contact

You may call crdl(contact) to add or update a contact record.

crdl('contact', auth_data, contact_data)

You may pass an object with authentication data such as email address, or any other contact identifier value used in your account, subscribe status, attribute values, and list associations for a new or existing contact.

Note that some form of authentication data is required for creating or updating contact records.

Tip: The crdl(contact) method can be used in a similar manner to cordial.identify(), which is a JavaScript listener v1 method. Simply use this format:crdl('contact', {'auth_data': 'contactid'}, {}). The contact_data placeholder must be included but can be empty.

If available contact authentication data does not match the existing records, a new contact will be created using the passed authentication data as the contact identifier.

Note: If your account is configured to use the Cordial generated cID as the primary contact identifier, the authentication object value can be null. In this case, a contact record will be created and assigned a new cID.

An example of adding or updating a contact

This example is using email as the contact identifier. The authentication data object accepts primary and secondary contact identifier key/value pairs such as cID:58d2fc99ac0c8117814d4e78 or customKey: value.

var auth_data = {

email: '[email protected]'

}

var contact_data = {

'channels': {

'email': {

'subscribeStatus': 'subscribed',

}

},

'first_name': 'Fred',

'age': '32',

'platinum': true

};

crdl('contact', auth_data, contact_data);

The use of subscribeStatus key is situational and may not be necessary for all contact creation and update calls.

Subscribe status should only be set to "subscribed" if the contact has explicitly consented to receive promotional messages. The default subscribe status is "none".

For example, if during the checkout process a new contact chooses not to receive promotional emails, it is not necessary to explicitly set their subscribe status to "unsubscribed", being that as a new contact without prior subscriptions, their subscribe status is initially set to "none". The best way to accomplish this is to leave the subscribeStatus key out of the call entirely.

If, however, the contact indicates by checking a box (or some other way) that they would like to receive promotional emails, the subscribeStatus key with the value of "subscribed" should be passed as demonstrated here:

var contact_data = {};

contact_data.channels = {};

contact_data.channels.email = {};

contact_data.channels.email.address = '[email protected]';

if(your_logic_for_box_checked){

contact_data.channels.email.subscribeStatus = 'subscribed';

}

var auth_data = {};

auth_data.email = contact_data.channels.email.address;

crdl('contact', auth_data, contact_data);

An example of adding or updating a contact if authentication data is not available

If authentication data is not available (null), the current session BID will be used to look up and update any existing records matching the same BID. If the current session BID is not associated with any of the existing records, the call will be newly added and tracked in the anonymous history collection.

var auth_data = {

'email': null

}

var contact_data = {

'platinum': false

};

crdl('contact', auth_data, contact_data);

Examples of working with arrays

var data = {

'first_array': {'add': [1234]},

'second_array': {'remove': ['apple']},

'third_array': [1234, 5678]

};

crdl('contact', auth_data, contact_data);

crdl(event) - Tracking Custom Events

Events are stored in the contact activities collection. You may track an event by calling crdl(event) with the event action name and optional event properties object.

crdl('event', 'action_name', properties);

The event action name may be whatever you like, barring a select number of reserved event names.

Reserved event names

The following action names are already used for Cordial system events and should NOT be used for custom events:

click

open

message-sent

bounce

optout

Properties Object

You may also optionally pass a properties object of key/value pairs describing the event. Note that property keys may be custom-named.

Note: Property keys consisting of numeric-only values (e.g. 57) or keys containing a "dot" (e.g. shoes.color) will be stripped.

Example of adding a custom named event to the contact activities collection

In the example below, a custom named event with the action name "browse" will be tracked and added to the contact activities collection.

var properties = {

"category": "Shirts",

"url": "http://example.com/category/shirts"

};

crdl('event', 'browse', properties);

Example API Response of a Custom Event in the Contact Activities Collection

Below is an example of how the event data is stored within the contact activities collection. Note that each event will be given a timestamp, an event ID (_id) and a contact ID (cID).

{

"cID": "58d30719ac0c8117814da1f3",

"_id": "5902468650c860b06da54183",

"properties": {

"category": "shirts",

"url": "http://example.com/category/shirts",

"time": "2017-03-27T19:20:50+0000"

},

"action": "browse",

"time": "2017-03-27T19:20:50+0000",

"email": "[email protected]"

}

Searching & Segmenting on custom events

The property object's key/value pairs can be used for filtering the browse events for creating audiences. For example, an Audience Rule can be created to query all contacts who were tracked for a 'browse' event. Additionally, a filter can be added to the rule that queries all contacts who were tracked for a 'browse' event where the category is 'shirts'.

crdl(cartitem) - Updating Cart Items

Each contact record contains a cart object stored within the contacts collection.A user must first be in the Cordial Contacts Collection before adding cart information.

To add items to the cart, we recommend using 3 methods together that will:

Clear the cart

Add items to the cart

Create a custom named event called "cart"

crdl([

['cart', 'clear'],

['cartitem', 'add', cart_data],

['event', 'cart']

]);

Cart Item Object

* Required

Key

Description

Type

*productID

Item Identifier

string

*sku

Item Number

string

*category

Item Category

string

*name

Item Name

string

description

Item description

string

qty

Quantity in the cart

int

itemPrice

Price per item

float

url

Link to the item

string

images

image names or paths

array

attr

attribute value pairs

object

Example of Updating the Cart in the Contacts Collection

var cart_data = [{

'productID': '1234',

'sku':'1234-red',

'category':'shirts',

'name':'Red Shirt',

'images':['http://example.com/image1.jpg','http://example.com/image2.jpg'],

'description':'A cool red shirt.',

'qty': 1,

'itemPrice': 10.20,

'url':'http://example.com/pdp/1234',

'attr': {

'manufacturer': 'ExampleCo',

'size': 'L'

}

},

{

'productID': '5678',

'sku':'5678-blue',

'category':'shirts',

'name':'Blue Shirt',

'images':['http://example.com/image1.jpg','http://example.com/image2.jpg'],

'description':'A bright blue shirt.',

'qty': 2,

'itemPrice': 10.20,

'url':'http://example.com/pdp/5678',

'attr': {

'manufacturer': 'ExampleCo',

'size': 'L'

}

}];

crdl([

['cart', 'clear'],

['cartitem', 'add', cart_data],

['event', 'cart']

]);

Example API Response of the Cart Object from the Contacts Collection

Below is an example of how the cart data is stored within a contact's profile of the contacts collection. Note, the cartitem amount is automatically calculated (itemPrice x qty) and cart totalAmount is automatically calculated as the sum of all cart item amounts.

"cart": {

"cartitems": [{

"productID": "1234",

"sku": "1234-red",

"category": "shirts",

"name": "Red Shirt",

"images": [

"http://example.com/image1.jpg",

"http://example.com/image2.jpg"

],

"description": "A cool red shirt.",

"qty": 1,

"itemPrice": 10.2,

"url": "http://example.com/pdp/1234",

"attr": {

"manufacturer": "ExampleCo",

"size": "L"

},

"amount": 10.2

},

{

"productID": "5678",

"sku": "5678-blue",

"category": "shirts",

"name": "Blue Shirt",

"images": [

"http://example.com/image1.jpg",

"http://example.com/image2.jpg"

],

"description": "A bright blue shirt.",

"qty": 2,

"itemPrice": 10.2,

"url": "http://example.com/pdp/5678",

"attr": {

"manufacturer": "ExampleCo",

"size": "L"

},

"amount": 20.4

}],

"totalAmount": 30.6,

"lm": "2018-09-27T22:29:49+0000"

}

crdl(order) - Adding Orders

Calling crdl(order) will add orders to the orders collection with a new record for the individual contact.

To add an order, we recommend using 3 methods together that will:

Clear the cart

Add the order data

Create a custom named event called "order"

crdl([

['cart', 'clear'],

['order', 'add', cart_data],

['event', 'order']

]);

Order Object

* Required

Key

Description

Type

Example

Order

*orderID

Unique identifier assigned for the order

string

33451

customerID

An ID value assigned by the ecommerce or CRM system

string

abc123

tax

The amount of the tax

float

22.50

shippingAndHandling

The amount charged for shipping and handling

float

0.0

shippingAddress

name, address, city, state, postalCode, country

object

see below

billingAddress

name, address, city, state, postalCode, country

object

see below

*items

Each object describes an item of the order

array of objects

See parameters per item object below

Parameters per each item object

*productID

A unique identifier for the product.

string

1234abcd

*sku

The Stock Keeping Unit value for a particular item.

string

RF-WP33286-21

*category

The category given to the particular item.

string

Major Appliance

*name

The name of the product

string

S22-Refrigerator

*qty

The quantity of this item purchased.

integer

1

description

Description of the product

string

Great product!

url

Link to the product

string

http://myproduct.com

attr

Key value pairs describing the attributes of the product

object

"size":"large", "color":"red"

itemPrice

The item's retail price.

float

129.95

Optional parameters for billingAddress and shippingAddress objects

name

The name of the person or company making the order.

string

Mark Smith

address

Defines the street address.

string

13130 Silverlake Road

city

Defines the city

string

Hollywood

state

Defines the state

string

CA

postalCode

Defines the postal code

integer

90028

country

Defines the country

string

USA

Example of Adding an Order to the Orders Collection

var order_data = {

"orderID": "12345",

"shippingAddress": {

"name": "Chris",

"address": "123 Main St",

"city": "San Diego",

"state": "CA",

"postalCode": 92107,

"country": "US"

},

"billingAddress": {

"name": "Chris",

"address": "123 Main St",

"city": "San Diego",

"state": "CA",

"postalCode": 92107,

"country": "US"

},

"items": [{

"productID": "1234",

"sku": "1234-red",

"category": "shirts",

"name": "Red Shirt",

"qty": 1,

"itemPrice": 2.0

}]

};

crdl([

['cart', 'clear'],

['order', 'add', order_data],

['event', 'order']

]);

Example API Response of an Order from the Orders Collection

{

"_id": "5bad60450190d43159af5a2b",

"orderID": "12345",

"shippingAddress": {

"name": "Chirs",

"address": "123 Main St",

"city": "San Diego",

"state": "CA",

"postalCode": "92107",

"country": "US"

},

"billingAddress": {

"name": "Chirs",

"address": "123 Main St",

"city": "San Diego",

"state": "CA",

"postalCode": "92107",

"country": "US"

},

"items": [{

"productID": "1234",

"sku": "1234-red",

"category": "shirts",

"name": "Red Shirt",

"qty": 1,

"itemPrice": 2,

"amount": 2

}],

"totalAmount": 2,

"cID": "595197c8ac0c811781e176b4",

"purchaseDate": "2018-09-27T22:57:09+0000"

}

crdl(param-store) - Storing Parameters

If crdl(param-store) is set, the track script will pull values out of the URL query string for any of the defined keys. The values will be stored in cookies and will be available for retrieval as variables. Stored parameters can be used to track and run reports on Google AdWords, traffic sources or other URL query string values.

For example, if you were using an ad service to drive traffic, your URLs may look like this:

http://mydomain.com?utm_source=google&utm_campaign=1234.

You can telltheembedded script which URL query string parameters to listen for:

crdl('param-store', "utm_source,utm_campaign");

The listener will now look for those query string keys and store their values in a cookie. The values are automatically available to you as variables. For example:

cordial.utm_source

cordial.utm_campaign

You can tell the script to listen for specificquery parameters, as long as the keys in the URL are alphanumerical. The keys may also contain: "-" and "_". Multiple keys should be comma separated.

You can use the variables in a number of ways, but a common use case would be to pass them as attribute values. The following example assumes an account with attributes called "source" and "campaign". When adding or updating a contact, you could pass the following variables.

cordial.contact({

"source":cordial.utm_source,

"campaign":cordial.utm_campaign

})

If the contact arrived at the page from the URL above, their profile would include the following:

"source": "google",

"campaign": "1234",

...

crdl(forget) - Clearing cookies

Calling crdl('forget') will clear the cookies and assign a new browser ID. Useful for logout events and cleaning the current browsing session.

crdl('forget')

API Set Name: contacts

GET /contacts

POST /contacts

DELETE /contacts/{primary_key}

GET /contacts/{primary_key}

PUT /contacts/{primary_key}

PUT /contacts/{primary_key}/unsubscribe/{channel}

DELETE /contacts/{primary_key}/cart

POST /contacts/{primary_key}/cart

PUT /contacts/{primary_key}/cart

POST /contacts/{primary_key}/cartitems

DELETE /contacts/{primary_key}/cartitems/{productID}

DELETE /contacts/{primary_key}/cartitems/{productID}/{qty}

POST /contacts/{primary_key}/downloadprofile

API Description and Functional Purpose:

The contacts collection contains all contacts and their associated attribute, list and channel data.

Additional information:

Cordial keeps track of contact data by assigning at least one unique identifier to all contact records. Default primary and secondary contact identifier keys can be configured uniquely for each Cordial account based on clients' data infrastructure.

A contact can have multiple attribute key/value pairs such as First Name, Last Name, etc. provided an attribute has been previously defined within the account contact attributes collection.

A contact can be associated to one or more lists, stored in the contact collection as an array of key/value pairs.

Validators assigned to each attribute are enforced when attribute data is added or updated within the contact collection.

Validators changed after data is added will not affect existing saved data nor will they force revalidation. However, edits to that data may.

Contact activity data resides in the contact activities collection and is associated back to the contact via its primary key, currently the email address.

Resource Associations:

The following resource collections are associated to this collection.

Collection

Association

account contact attributes

Attribute data can be added to a contact based on the existence of account contact attributes.

contact activities

Contacts are linked to their activities by their primary or secondary identifier keys.

account lists

Contacts can be associated to account lists, identifying a contact as a member of one or more lists.

orders

Order data will be included in the response for the GET method, provided there is available order data for that contact.

GET /contacts

Method

URI Path

GET

/contacts

Retrieves all contacts from the Cordial database.

Using query string parameters (see example URIs below) it is possible to:

Filter the response by primary or secondarycontact identifierto retrieve information for a single contact.

Filter the response by an audience key to limit the response to a certain audience.

Filter the response by an attribute key to limit the attribute data to a specific value.

Apply per_page and page query string parameters to limit the count returned and page position for large responses.

Sort response by a specific column/field (ascending or descending order).

Parameters

Parameter

Type

Description

Example

contact identifier

string

Unique contact identifier value to look up and reference the contact.

[email protected], ID1234, 16198880000

audience-key

string

The name of the audience for filtering contacts.

30_Day_Engaged

sort_by

string

Columnto sort by

lastModified

sort_dir

string

Direction to sort by, works in conjunction with sort_by

Possible Values:

asc, desc

asc

page

number

Page number of results

2

per_page

number

Number of results per page

20

return_count

boolean

The number of records returned. The default is false.

Possible Values:

true, false

true

Example GET Request URIs

Retrieve All Contacts

The following URI will retrieve all contacts and include all account contact attributes fields:

http://<path>/contacts

Filter Results By Email

The following URI will retrieve a contact and its associated account contact attributes whereemail is theidentifier:

http://<path>/contacts/email:[email protected]

Filter Results By cID

The following URI will retrieve a contact and its associated account contact attributes where the cID is "58d2fc99ac0c8117814d4e78":

Note: In the API response, cID is referred to as "_id".

http://<path>/contacts/cID:58d2fc99ac0c8117814d4e78

Filter Response By Audience Key

The following URI will retrieve contacts within the audience using the audience key(or name) of "clicked".

http://<path>/contacts?audience-key=clicked

Filter Response By Attribute Key

The following URI will retrieve all contacts where the value for the contact attribute gender is "male".

http://<path>/contacts?gender=male

Page Request Parameters

The following URI will retrieve all contacts starting from the third page grouping contacts by 10. For example, page 1 would have included the first 10, page 2 the second group of 10 and so on.

http://<path>/contacts?page=3&per_page=10

Return Count

The following URI will retrieve a count of all contacts in the request:

http://<path>/contacts?return_count=true

Note: Get /contacts can process a maximum of 10k contacts. For example, a request for 1k contact records per page will return contact records for pages 1 through 10 but it will not return records on the 11th page. If it is necessary to access more that 10k contact records, the contactexport api call should be used.

POST /contacts

Method

URI Path

POST

/contacts

Creates a new contact in the Cordial database using the appropriate JSON body.

Contacts can optionally include attribute values and list association. Note that list and contact attributes keys must be created prior to the POST /contacts method with the UI, or the API using the accountcontactattributes and accountlists methods.

Parameters

* Required

Parameter

Type

Description

Example

*address

string

Unique email address to identify and reference the contact. This is the default primary key for contacts.

[email protected]

subscribeStatus

string

Promotional messages will not be sent unless set to "subscribed". Default is "none".

Possible Values:

none, subscribed or unsubscribed

subscribed

invalid

boolean

No email message will be sent unless set to "false". Default is "false".

Possible Values:

true, false

false

string attribute key

string

Adds a string attribute value when the attribute type is set as "string".

Mark

date attribute key

ISO 8601 date

Adds a dater attribute value when the attribute type is set as "date".

2015-10-09T07:40:00.000Z

number attribute key

number

Adds a number attribute value when the attribute type is set as "number".

22

geo attribute key

geo

Adds a geo attribute value when the attribute type is set as "geo". Note that geo attributes contain following set schema of key names:

street_address

street_address2

city

state

postal_code

country

tz (time zone)

loc

lat (latitude)

lon (longitude)

Geo attributes may be added/updated using dot notation or an array of key/value pairs.

"<geo_key>.city": "San Diego"

or

"<geo_key>": {

"city": "San Diego"

},

array attribute key

array

Adds array attribute values when the attribute type is set as "array".

The default behavior is to replace the array value with the provided one. An object specifying add/remove behavior can be specified to override the default. If the max items limit is exceeded (default is 25), newer values will replace the oldest values.

["apple","banana","orange"]

To add a value:

{ "add": ["apple"] }

To remove a value:

{ "remove": ["banana"] }

list key

boolean

Adds or removes the contact from a list.

Possible Values:

true, false

true

forceSubscribe

boolean

If unsubscribed, this key must be used to update subscribeStatus to subscribed

Possible Values:

true, false

true

suppressTriggers

boolean

If true, will suppress message triggers that are based on updates to contact attribute values. Defaults to true.

false

Example JSON Request (minimum requirements)

The following will create a new contact with the email "[email protected]".

{

"channels": {

"email": {

"address": "[email protected]"

}

}

}

Example JSON Request (with subscribe status, contact attributes and list assignment)

The following will create a new contact for the email [email protected] with contact attribute values (first_name, last_name, age, location.postal_code) and list assignments (auto-enthusiast and safe-driver). Note that the contact attribute keys and list keys were created prior to the POST /contacts using the POST /accountcontactattributes and POST /accountlists API calls.

{

"channels": {

"email": {

"address": "[email protected]",

"subscribeStatus": "subscribed"

}

},

"first_name": "Mark",

"last_name": "Smith",

"location.postal_code": "92613",

"age": 32,

"auto-enthusiast": true,

"safe-driver": true

}

Note:

If subscribe status is not set, it will default to "none". Other available options are "subscribed" and "unsubscribed".

Contact attributes must already exist in the system to add their values. Contact attributes can be added using the POST /accountcontactattributes API call.

Lists must already exist in the system to add their assignment. Lists can be added using the POST /accountlists API call.

List assignment is determined by a boolean value, "true" or "false".

"location.postal_code" is a geo attribute where the key is "location".

Geo attributes contain the following set schema of key names:

street_address

street_address2

city

state

postal_code

country

tz (time zone)

loc

lat (latitude)

lon (longitude)

Example JSON Request (resubscribing a contact)

The following will resubscribe a contact and override the previously set unsubscribe flag. It will also set the invalid flag to false.

Note: Setting the invalid flag to false will override a hard bounced email address.

{

"channels": {

"email": {

"address": "[email protected]",

"subscribeStatus": "subscribed",

"invalid": false

}

},

"forceSubscribe": true

}

Example POST Request URI

The following URI in conjunction with the JSON will perform the POST.

http://<path>/contacts

DELETE /contacts/{primary_key}

Method

URI Path

DELETE

/contacts/{primary_key}

/contacts/{secondary_key}:{value}

Deletes a contact from the Cordial database.

The primary_key is defined by the primary contact identifier value.

The secondary_key is defined by the secondary contact identifier key and value.

Example DELETE Request URI

The following URI will delete a contact and its associated account attribute values where email is theprimary contact identifier:

http://<path>/contacts/[email protected]

The following URI will delete a contact and its associated account attribute values where email is thesecondary contact identifier:

http://<path>/contacts/email:[email protected]

GET /contacts/{primary_key}

Method

URI Path

GET

/contacts/{primary_key}

/contacts/{secondary_key}:{value}

Retrieves a single contact from the Cordial database.

The primary_key is defined by the primary contact identifier value.

The secondary_key is defined by the secondary contact identifier key and value.

Example GET Request URI

The following URI will retrieve a contact record and its associated account attribute values with the primary key value of "[email protected]".

http://<path>/contacts/[email protected]

PUT /contacts/{primary_key}

Method

URI Path

PUT

/contacts/{primary_key}

/contacts/{secondary_key}:{value}

Updates a contact within the Cordial database using the appropriate JSON body.

The primary_key is defined by the primary contact identifier value.

The secondary_key is defined by the secondary contact identifier key and value.

Parameters

See the parameters for POST /contacts above.

Example JSON Requests

Update a String Attribute

The following will update the contact's first_name string attribute to "Markus".

{

"first_name": "Markus"

}

Update an Number Value

The following will update the contact's points number attribute to 75.

{

"points":75

}

The following will increment the contact's points number attribute by 15.

{

"points": {

"inc": 15

}

}

The following will decrement the contact's points number attribute by 15.

{

"points": {

"inc": -15

}

}

Update an Array Value

The following will update the contact's fav_fruits array attribute with the value "banana". Note that this will overwrite any existing array values.

{

"fav_fruits": ["banana"]

}

The following will update the contact's fav_fruits array attribute with "banana" and "strawberry". Note this will overwrite existing array values.

{

"fav_fruits": ["banana", "strawberry"]

}

The following will add the value "apple" to the contact's fav_fruits array attribute. Existing values will be retained unless the max items limit is exceeded (default 25).

{

"fav_fruits": {

"add": ["apple"]

}

}

Note: If the number of array values exceeds the max items limit (default 25), the oldest values will be replaced with the newest values. The max items limit can be set using a POST or PUT Account Contact Attributes API call.

The following will remove the value "apple" and "strawberry" from the contact's fav_fruits array attribute.

{

"fav_fruits": {

"remove": ["apple", "strawberry"]

}

}

Update List Assignment

The following will update the list assignments of safe-driver and premium-roadside-assistance for the contact. Note that the lists were created prior to updating the contact using the POST /accountlists API call.

{

"safe-driver": false,

"premium-roadside-assistance": true

}

Update Email Address

The following will update the email address for the contact.

{

"channels": {

"email": {

"address": "[email protected]"

}

}

}

Example PUT Request URI

The following URI in conjunction with the JSON will perform the PUT for the contact with the primary key of "[email protected]".

http://<path>/contacts/[email protected]

PUT /contacts/{primary_key}/unsubscribe/{channel}

Method

URI Path

PUT

/contacts/{primary_key}/unsubscribe/{channel}

/contacts/{secondary_key}:{value}/unsubscribe/{channel}

Unsubscribes a contact within the Cordial database per channel.

The primary_key is defined by the primary contact identifier value. The channel is the specified channel ("email" for example).

The secondary_key is defined by the secondary contact identifier key and value.

Parameters

* Required

Parameter

Type

Description

Example

mcID

string

The message contact ID for attribution to a sent message.

252:58ffed51f0c36063476c1752:ot:58d30719ac0c8117814da1f3:1

Example PUT Request URI

The following URI will set the subscribe status to "unsubscribed" in the "email" channel of the contact with a primary key of "[email protected]".

http://<path>/contacts/[email protected]/unsubscribe/email

The following URI will unsubscribe the contact and attribute the unsubscribe to a specific message using the mcID.

http://<path>/contacts/[email protected]/unsubscribe/email?mcID=252:58ffed51f0c36063476c1752:ot:58d30719ac0c8117814da1f3:1

DELETE /contacts/{primary_key}/cart

Method

URI Path

DELETE

/contacts/{primary_key}/cart

/contacts/{secondary_key}:{value}/cart

Removes cart object from the contact.

The primary_key is defined by the primary contact identifier value.

The secondary_key is defined by the secondary contact identifier key and value.

Example DELETE Request URI

The following URI will delete the cart object from the contact with a primary key of [email protected].

http://<path>/contacts/[email protected]/cart

POST /contacts/{primary_key}/cart

Method

URI Path

POST

/contacts/{primary_key}/cart

/contacts/{secondary_key}:{value}/cart

Adds a cart object to the contact.

The primary_key is defined by the primary contact identifier value.

The secondary_key is defined by the secondary contact identifier key and value.

Parameters

* Required

Parameter

Type

Description

Example

mcID

string

Message Contact ID

264:590261c7f0c360ee35a8046f:ot:5900ddf2ac0c81178189d93b:1

customerID

string

Customer ID

38583

linkID

string

Link ID

1234

url

string

Cart URL

http://example.com

Cart Items

*productID

string

Item Identifier

GreenPlaid123123

*sku

string

Item Number

111222333

*category

string

Item Category

Shirts

*name

string

Item Name

Green Plaid

description

string

Item description

Awesome shirt

qty

int

Quantity in the cart

2

itemPrice

number

Price per item

10.99

url

string

Link to the item

http://www.shirts.com/GreenPlaid123123

images

array

image names or paths

["image1.jpg","image2.jpg"]

properties

object

property value pairs

{ "style": "v-neck", "material": "cotton" }

attr

object

attribute value pairs

{ "size": "small", "color": "red" }

Example JSON Request

{

"mcID": "264:590261c7f0c360ee35a8046f:ot:5900ddf2ac0c81178189d93b:1",

"customerID": "1234",

"linkID": "1234",

"url": "http:example.com",

"cartitems": [{

"productID": "GreenPlaid123123",

"name": "Green Plaid",

"sku": "111222333",

"category": "Shirts",

"qty": 2,

"images": ["image1.jpg", "image2.jpg"],

"itemPrice": 10.99,

"amount": 21.98,

"description": "Awesome shirt",

"url": "http://www.shirts.com/GreenPlaid123123",

"attr": {

"size": "small",

"color": "green"

},

"properties": {

"style": "v-neck",

"material": "cotton"

}

},

{

"productID": "BluePlaid123123",

"name": "Blue Plaid",

"sku": "111222444",

"category": "Shirts",

"qty": 1,

"itemPrice": 10.99,

"amount": 10.99,

"description": "Awesome shirt",

"url": "http://www.shirts.com/BluePlaid123123",

"attr": {

"size": "small",

"color": "blue"

},

"properties": {

"style": "v-neck",

"material": "cotton"

}

}

]

}

Example POST Request URI

The following URI in conjunction with the JSON will add the cart object for the contact with the primary key value of "[email protected]".

http://<path>/contacts/[email protected]/cart

PUT /contacts/{primary_key}/cart

Method

URI Path

PUT

/contacts/{primary_key}/cart

/contacts/{secondary_key}:{value}/cart

Updates the cart object for the contact.

The primary_key is defined by the primary contact identifier value.

The secondary_key is defined by the secondary contact identifier key and value.

Parameters

See parameters above for POST /contacts/{primary_key}/cart.

Example JSON Request

See example above for POST /contacts/{primary_key}/cart.

Example PUT Request URI

The following URI in conjunction with the JSON will update the cart object for the contact with the primary key of "[email protected]".

http://<path>/contacts/[email protected]/cart

POST /contacts/{primary_key}/cartitems

Method

URI Path

POST

/contacts/{primary_key}/cartitems

/contacts/{secondary_key}:{value}/cartitems

Adds a product to the cart.

The primary_key is defined by the primary contact identifier value.

The secondary_key is defined by the secondary contact identifier key and value.

Parameters

* Required

Parameter

Type

Description

Example

*productID

string

Item Identifier

GreenPlaid123123

*sku

string

Item Number

111222333

*category

string

Item Category

Shirts

*name

string

Item Name

Green Plaid

description

string

Item description

Awesome shirt

qty

int

Quantity in the cart

2

itemPrice

number

Price per item

10.99

url

string

Link to the item

http://www.shirts.com/GreenPlaid123123

images

array

image names or paths

["image1.jpg","image2.jpg"]

properties

object

property value pairs

{ "style": "v-neck", "material": "cotton" }

attr

object

attribute value pairs

{ "size": "small", "color": "red" }

Example JSON Request

{

"productID": "PurplePlaid123123",

"name": "Green Plaid",

"sku": "111222333",

"category": "Shirts",

"qty": 2,

"images": ["image1.jpg", "image2.jpg"],

"itemPrice": 10.99,

"amount": 21.98,

"description": "Awesome shirt",

"url": "http://www.shirts.com/PurplePlaid123123",

"properties": {

"size": "large",

"color": "Purple"

}

}

Example POST Request URI

The following URI in conjunction with the JSON will add an item to the cart of the contact with the primary key value of "[email protected]".

http://<path>/contacts/[email protected]/cartitems

DELETE /contacts/{primary_key}/cartitems/{productID}

Method

URI Path

DELETE

/contacts/{primary_key}/cartitems/{productID}

/contacts/{secondary_key}:{value}/cartitems/{productID}

Removes a product from the cart.

The primary_key is defined by the primary contact identifier value.

The secondary_key is defined by the secondary contact identifier key and value.

Example DELETE Request URI

The following URI will delete the cart item with the productID of "PurplePlaid123123" for the contact with the primary key value of "[email protected]".

http://<path>/contacts/[email protected]/cartitems/PurplePlaid123123

DELETE /contacts/{primary_key}/cartitems/{productID}/{qty}

Method

URI Path

DELETE

/contacts/{primary_key}/cartitems/{productID}

/contacts/{secondary_key}:{value}/cartitems/{productID}

Removes a product from the cart by quantity.

The primary_key is defined by the primary contact identifier value.

The secondary_key is defined by the secondary contact identifier key and value.

Example DELETE Request URI

The following URI will delete quantity of "1" from the cart item with the productID of "PurplePlaid123123" for the contact with the primary key value of "[email protected]".

http://<path>/contacts/[email protected]/cartitems/PurplePlaid123123/1

POST /contacts/{primary_key}/downloadprofile

Method

URI Path

POST

/contacts/{primary_key}/downloadprofile

/contacts/{secondary_key}:{value}/downloadprofile

Creates an export job to download and store a JSON file of a contact's profile (including event data) from the Cordial database.

The primary_key is defined by the primary contact identifier value.

The secondary_key is defined by the secondary contact identifier key and value.

Parameters

* Required

Parameter

Type

Description

Example

* Destination

Note: Destination parameters are only required if SFTP or FTP is used as the destination. If parameters are not supplied, or set as AWS, the exported file can be downloaded through the UI.

type

string

Defines the destination type.

Possible Values:

aws, ftp, sftp

sftp

server (required if type is ftp or sftp)

string

Domain or IP address of the SFTP server.

sftp.example.com

port (required if type is ftp or sftp)

number

Defines the port number for the FTP or SFTP server.

22

username (required if type is ftp or sftp)

string

Defines the username for FTP or SFTP authentication.

username

password (required if type is ftp or sftp)

string

Defines the password for FTP or SFTP authentication.

password

path (required if type is ftp or sftp)

string

Defines the path to the folder.

/folder

Example JSON Requests

The following will initiate an export job of a JSON file containing all profile data (including events) of the specified contact, downloadable via the UI on the Jobs page.

{

"destination": {

"type": "aws"

}

}

The following will initiate an export job of a JSON file via SFTP containing all profile data (including events) of the specified contact.

{

"destination": {

"type": "sftp",

"server": "example.com",

"port": "21",

"username": "username",

"password": "password",

"path": "/"

}

}

Example Request URIs

The following URI in conjunction with the JSON will perform the POST.

http://<path>/contacts/{primary_key}/downloadprofile

API Set Name: contactactivityexport

POST /contactactivityexport

API Description and Functional Purpose:

The contactactivityexport resource creates an export job to download and store a file of contact activities from the Cordial database to an external location.

Additional information:

This resource uses the JSON request information to define the target host location of the file, the transport protocol, the external host login authentication information and the fields to include in the file.

It is important to note that this resource is not a collection of exports, but is a resource that initiates export processing by creating an export job.

Export status information is available through the "jobs" resource.

Export supports file type "CSV" and "JSON".

Export files in the UI will be stored for 30 days from the date of the export.

Note: Due to the potential for large file size and processing time when exporting contact activities, it is recommended to test with smaller exports. To reduce file size, you can limit by date range, event name, message type, as well as chunk and compress files.

POST /contactactivityexport

Method

URI Path

POST

/contactactivityexport

Creates an export job using the JSON body information.

Parameters

* Required

Parameter

Type

Description

Example

name

string

Defines the name of file for destination type FTP or SFTP.

ExportClickEvents

*exportType

string

Defines the type of the file to be exported. If value is JSON and no columnHeaders are specified, all columns will be exported.

Possible Values:

CSV, JSON

JSON

selected_timeframe_start

string

Start date and time of selected timeframe to be exported.

2017-11-01T15:28:04.124Z

selected_timeframe_end

string

End date and time of selected timeframe to be exported.

2017-11-03T15:28:04.124Z

selected_action_name

string

Defines the message or custom events to be exported.

Possible Values:

message-sent, open, click, optout, bounce, complaint, custom

open

selected_action_names

array

Defines the array of message or custom events to be exported.

Possible Values:

message-sent, open, click, optout, bounce, complaint, custom

open, click, bounce, optout

selected_message_type

string

Defines the message type events to be exported.

Possible Values:

batch, automation

batch

showAllProperties

boolean

For use when selected_action_name is supplied (ex: bounce). When true, will export columns for all event system properties. Event system properties can also be defined in the ColumnHeaders object.

Possible Values:

true, false

true

showHeader

boolean

For use when export type is "CSV" to determine if first row displays column names.

Possible Values:

true, false

true

selected_message_id

string

Defines the message ID to be exported.

Possible Values:

bmID or mdtID

45:5a7d2a3cc7280b410:ot

limitRecordsPerFile

integer

Defines the number of records per file chunk to be exported. If no value is passed, all records that match the filters will be exported to one file.

500000

compress

boolean

Compresses the exported file. If value is true, the file is compressed using GZIP with the file extension ".gz" added to the filename(s). See note below table regarding file availability.

Possible Values:

true, false

true

selected_contact

string

Defines the contract for the associated records to be exported.

Possible Values:

A valid primary or secondary contact identifier value.

[email protected], ID1234, 16198880000

selected_audience_key

string

Defines the audience rule for the associated records to be exported.

vip_members

confirmEmail

email

Email address to send an administrative alert that the import job has been completed.

[email protected]

Destination

Note: Destination type "aws" should be used if the file is to be downloaded via the UI.

If Destination type "S3", API calls should be made using /v2/contactactivityexport.

type

string

Defines the destination type.

Possible Values:

aws, ftp, sftp, s3

sftp

server (required if type is ftp or sftp)

string

Domain or IP address of the SFTP server.

sftp.example.com

port (required if type is ftp or sftp)

number

Defines the port number for the FTP or SFTP server.

22

username (required if type is ftp or sftp)

string

Defines the username for FTP or SFTP authentication.

username

password (required if type is ftp or sftp)

string

Defines the password for FTP or SFTP authentication.

password

aws_access_key_id (required if type is s3)

string

Defines the public AWS id.

A1234567890

aws_secret_access_key(required if type is S3)

string

Defines the secret AWS key.

B1234567890

aws_bucket (required if type is S3)

string

Defines the AWS bucket name.

bucket

aws_region (required if type is S3)

string

Defines the AWS region.

us-west-2

path (required if type is ftp, sftp or S3)

string

If type is S3: path to folder and file. If type is FTP or SFTP: path to folder.

S3: /folder/contactsExport.csv FTP: /folder

ColumnHeaders

For use when explicitly defining the output column headers. If no column headers are provided, the following default column headers will be included in the CSV output file. A JSON file type will export all column headers if none provided.

action

time

bmID

cID

email (if the primary identifier key is "email", otherwise the default primary key for the account)

name

string

Name of column in Cordial system.

email

label

string

Label for column which will be represented in file.

Contact

Note: When destination type is "S3", if compress value is false and limitRecordsPerFile is set, each chunk will be uploaded as soon as it's ready. If compress value is true and limitRecordsPerFile is set, all chunks will be uploaded together when the export is complete.

Example JSON Requests

The following will initiate an export job of all batch message sent activities for Feb 2nd into a CSV file that will be available for download via the UI.

{

"name": "batch-30days",

"exportType": "csv",

"destination": {

"type": "aws"

},

"showHeader": true,

"selected_timeframe_start": "2018-02-01T00:00:00.000Z",

"selected_timeframe_end": "2018-02-27T23:59:59.999Z",

"selected_message_type": "batch",

"selected_action_name": "message-sent",

"compress": false,

"confirmEmail":"[email protected]"

}

The following will initiate an export job of all batch message sent activities for Feb 2nd into a CSV file via FTP download.

{

"name": "batch-30days",

"exportType": "csv",

"destination": {

"type": "ftp",

"server": "ftp.example.com",

"port": 21,

"username": "[email protected]",

"password": "cordial",

"path": "./"

},

"showHeader": true,

"selected_timeframe_start": "2018-02-01T00:00:00.000Z",

"selected_timeframe_end": "2018-02-27T23:59:59.999Z",

"selected_action_names": "message-sent", "open", "click"

"selected_message_type": "batch",

"compress": false,

"confirmEmail":"[email protected]"

}

The following will initiate an export job of all bounce events into a JSON file via FTP download. Note that each record is returned as a separate line consisting of a single JSON object (not an array of JSON objects).

Note: Some system and custom-named events (i.e. bounce, browse) may have additional properties (i.e. system_properties, category, product, etc.). You are able to export the values within the properties object using dot notation. For example: system_properties.bt, properties.category or properties.product.

{

"name": "bounce-30days",

"exportType": "json",

"destination": {

"type": "ftp",

"server": "ftp.example.com",

"port": 21,

"username": "[email protected]",

"password": "password",

"path": "./"

},

"selected_timeframe_start": "2018-02-01T00:00:00.000Z",

"selected_timeframe_end": "2018-02-27T23:59:59.999Z",

"selected_action_name": "bounce",

"showAllProperties":false,

"compress": false,

"confirmEmail":"[email protected]",

"columnHeaders": [

{

"name": "_id",

"label": "_id"

},

{

"name": "action",

"label": "action"

},

{

"name": "email",

"label": "email"

},

{

"name": "cID",

"label": "cID"

},

{

"name": "bmID",

"label": "msID"

},

{

"name": "mcID",

"label": "mcID"

},

{

"name": "mdtID",

"label": "mdtID"

},

{

"name": "time",

"label": "time"

},

{

"name": "first",

"label": "first"

},

{

"name": "message_name",

"label": "message_name"

},

{

"name": "system_properties.bt",

"label": "system_properties_bt"

},

{

"name": "system_properties.link",

"label": "system_properties_link_key"

},

{

"name": "system_properties.rl",

"label": "system_properties_redirect_link"

},

{

"name": "properties.custom_per_client_and_not_required",

"label": "properties_custom_per_client_and_not_required"

}

]

}

Learn how to add send properties to your export job.

For users of V1 POST /contactactivityexport, the following system names have been deprecated, but are still supported:

a

sp

ats

bmID

Example Request URIs

The following URI in conjunction with the JSON will perform the POST.

http://<path>/contactactivityexport

API Set Name: contactactivities

POST /contactactivities

GET /contactactivities

API Description and Functional Purpose:

The contact activities collection contains all contact-related activities such as opens, clicks, sends and any other user-defined actions. Contact activities are also referred to as "events".

Additional information:

Contact activities are associated to the contact via the contact's primary or secondary identifier key(s). Default primary and secondary contact identifier keys can be configured uniquely for each Cordial account based on client's data infrastructure.

A contact can have multiple contact activities documenting various action types.

Actions taken within a message will automatically generate an activity record.

Users can also create custom event activities such as "browse", "order", "clicked", etc.

Custom event activities can be added and acted upon through contact activities records in the Cordial database.

Contact activity data will be stored for 18 months, after which it will be systematically purged.

Resource Associations:

The following resource collections are associated to this collection.

Collection

Association

contacts

Contacts are linked to their activities by their primary or secondaryidentifier key(s).

POST /contactactivities

Method

URI Path

POST

/contactactivities

Creates a new contact activity in the Cordial database using the appropriate JSON body.

Parameters

* Required

Parameter

Type

Description

Example

*a

string

Defines an action such as an open or click, or any other defined action. The maximum length of the parameter is 40 characters.

browse

*contact identifier

string

Unique contact identifier value to look up and reference the contact.

[email protected], ID1234, 16198880000

ats

string

The action timestamp for the action. If this is left blank the current date and time will be used. Date format is ISO 8601 standard.

2018-01-09 17:47:43

properties

object

An object to record additional attributes of an event.

Note that property keys consisting of numeric-only values (e.g. 57) or keys containing a "dot" (e.g. shoes.color) will be stripped.

{"propertyOne": 1,

"propertyTwo": 2}

Note: When a property value is passed, its data type (string, integer, etc.) will be recognized and searchable in the platform UI. If a different data type is passed to an already recognized property, that new data will not be searchable in the UI. It is necessary to create a new property if the data type is to be changed.

Example JSON Requests

The following will create a new contact activity record for a user-defined "browse" event.

{

"a": "browse",

"email": "[email protected]",

"ats": "2018-01-09 17:47:43",

"properties": {

"category": "Shirts",

"url": "http://example.com/shirts",

"description": "A really cool khaki shirt.",

"price": 9.99,

"title": "Khaki Shirt"

}

}

Example Request URIs

The following URI in conjunction with the JSON will perform the POST.

http://<path>/contactactivities

GET /contactactivities

Method

URI Path

GET

/contactactivities

Retrieves contact activities from the Cordial database.

It is possible to retrieve contact activity records for all contacts or a specific contact.

It is also possible to filter based on date and time the contact activity occurred and by action names such as opens, clicks or any user-defined action. Options for time values include: lt, gt, lte, gte, between.start, between.end.

When retrieving a large number of contact activities, it is possible to apply per_page and page query string parameters to limit the count returned and page position.

GET /contactactivities is limited to retrieving a total of 10k records. If more than 10k records need to be retrieved, the /contactactivityexport API endpoint should be used.

Parameters

* Required

Parameter

Type

Description

Example

time

string

The action timestamp for the action.can be searched with modifiers (lt, gt, lte, gte, between.start, between.end).

2018-01-09 17:47:43

action

string

Can be click, open, message-sent, or any user-defined actions.

alarmTriggered

contact identifier

string

Unique contact identifier value to look up and reference the contact.

[email protected], ID1234, 16198880000

sort_by

string

Columnto sort by.

ats

sort_dir

string

Direction to sort by. Works in conjunction with sort_by.

desc

page

number

Page number of results.

2

per_page

number

Number of results per page.

20

return_count

boolean

The number of records returned. Default is false.

true

Note: Get /contactactivities can process a maximum of 10k records. For example, a request for 1k records per page will return records for pages 1 through 10 but it will not return records on the 11th page. If it is necessary to access more than 10k contact activity records, the /contactactivityexport API endpoint should be used.

Example Request URIs

The following URI will retrieve all contact activities.

http://<path>/contactactivities

The following URI will retrieve all contact activities where the emailaddress "[email protected]" is the contact identifier.

http://<path>/[email protected]

The following URI will retrieve all contact activities where the action is "browse".

http://<path>/contactactivities?action=browse

The following URI will retrieve all contact activities where the action is "browse" andemailaddress"[email protected]" is the contact identifier.

http://<path>/contactactivities?action=browse&[email protected]

The following URI will retrieve all contacts but only include the contact activities that have occurred between the specified start date and end date.

http://<path>/contactactivities?time[between][start]=2018-01-01&time[between][end]=2018-01-03

The following URI will retrieve all contacts but only include the "open" contact activities that have occurred between the specified start date and end date.

http://<path>/contactactivities?time[between][start]=2018-01-01&time[between][end]=2018-01-03&action=open

The following URI will retrieve all contact activities starting from the 3rd page and grouping contact activities by 10 per page. For example, page 1 would have included the first 10, page 2 the second group of 10 and so on. Note: The default per_page value is 25.

http://<path>/contactactivities?page=3&per_page=10

The following URI will return a count of all contact activities in the request:

http://<path>/contactactivities?return_count=true

In This Article

Overview

How Contact Attributes Are Stored

About Geo Attributes

Auto locate by IP address

Set as primary time zone

Adding Contact Attributes

Adding attributes via the UI

Adding attributes via CSV upload

Adding attributes via API

Using Contact Attributes in a Message

Building Audiences Using Attributes

Triggering Messages Using Attributes

Building Reports using Attributes

Audience trend reports

Filtering event dashboards

Filtering event data reports

Customize Attribute Access

Publicly editable

Retain data on delete

Used for:

Message Content

Building Audiences

Triggering Messages

Analytics

Overview

Contact attributes contain information specific to each contact and are stored in the contact collection as strings, numbers, dates, geo fields (addresses) and arrays. They are used throughout the system for creating personalized message content, building audiences for segmentation, triggering automated messages and viewing reports and analytics.

How Contact Attributes Are Stored

Below is a simple example of how contact attributes are stored in Cordial as a JSON object. Some data has been omitted for display purposes.

{

"channels": {

"email": {

"address": "[email protected]",

"subscribeStatus": "subscribed",

"unsubscribedAt": ""

}

},

"first_name": "Fred",

"last_name": "Garvin",

"customer_number": "3728",

"birthday": "1980-05-22T07:00:00+0000",

"home_address": {

"street_address": "555 Truss Ave",

"postal_code": "92108",

"country": "United States of America",

"state": "CA",

"city": "San Diego",

"tz": "America/Los_Angeles",

"loc": {

"lat": "32.7773",

"lon": "-117.1008"

},

"countryISO": "US",

"auto": false

},

"favorite_fruits": [

"apple",

"peach",

"pear"

]

}

Notice in the above example:

The channels object contains the email address and is the primary key for the contact.

The attribute keys that were created for the contact:

first_name: string value

last_name: string value

customer_number: number value

birthday: date value

home_address: geo object with a reserved set of field names

favorite_fruits: array of values

About Geo Attributes

Geo attributes store information about a contact's address. Multiple geo attributes can be created to represent multiple addresses (billing address, shipping address, etc.). Geo attributes contain the following reserved set of field names that cannot be edited:

street_address

street_address2

city

state

postal_code

country

tz (time zone)

loc

lat (latitude)

lon (longitude)

When a zip code is added, the following fields will be automatically added by the system:

City

State

Country

Timezone

Latitude and longitude

Note: Automatically populating geo attributes based on zip code is currently limited to U.S. zip codes only. Foreign zip codes may not populate geo attributes accurately.

Auto locate by IP address

When "auto locate by IP address" is set for a geo attribute, the following geo attribute data will be auto-populated based on the IP of the most recently observed behavior (opens, clicks or any custom events).

City

State

Zip code

Country

Timezone

Latitude and longitude

Note: Some email inbox providers (such as Gmail) may not pass the appropriate IP address for accurate auto location. This is generally due to the provider caching and opening emails on proxy servers.

Note: Auto populated data will overwrite any existing data for this attribute. To store location-based data explicitly provided by the contact (i.e. shipping or billing addresses) consider using a geo attribute which is not set to auto-locate.

To set auto locate by IP address navigate to Data Contact Attributes, hover over the arrow on the desired geo attribute and choose auto locate by IP address.

learn about lists

The icon will be added next to the attribute to designate the setting.

Note: Geo attribute data will only be auto populated on "live" message sends. Data will not be populated when a message is sent as a test message.

Set as primary time zone

A string or geo location attribute can be set as a contact's primary time zone for scheduled sending.

Note: The time zone must adhere to the "Area/Location" format (e.g. "America/New_York"). View the full list of recognized time zone identifiers.

To set an attribute as the primary time zone, navigate to Data Contact Attributes, hover over the arrow on the desired attribute and choose "Set as primary time zone".

The icon will be added next to the attribute as the primary time zone designation.

Once the primary time zone attribute is set, you will have the option to send based on contact's time zone across all messaging channels.

Note: If sending according to contact's time zone is not enabled, your message will be sent based on your Cordial account default time zone.

Adding Contact Attributes

Before contacts and their associated attribute data can be added to the Cordial system, each attribute's name and key must be added first.

Note: The contact email address is a reservedattribute keyand does not need to be added to the system like other attribute keys. It's key is referenced as channels.email.address.

Contact attribute keys can be added to the Cordial platform 3 ways:

Via the UI

Via CSV upload

Via API

Tip: For a better user experience, if you have a large amount of attributes it is recommended to create them in the UI prior to uploading contacts.

Adding attributes via the UI

Log into the Cordial platform and navigate to Data Contact Attributes

Click the button labeled "New" to create a new contact attribute.

Fill out the form to add the contact attribute to the system.

Attribute Name - Use this "friendly name" to reference the attribute within the application when searching and building audiences.

Attribute Key - This is the Attribute's ID and is referenced when personalizing content in messages and making API calls.

Note: When creating attribute keys, refrain from using math operators in place of spaces (-, +, *, etc) as they can cause errors with Smarty variables in message creation. We recommend using either camel case (firstName) or underscores (first_name).

Attribute Type - Choose the data type of the attribute

String - Any combination of characters

Number - Only numeric values

Date - Only date values (Examples: 01/30/2000, 2000-01-30, or2000-01-30T00:00:00Z)

Array - A comma separated list of values (Max Number of Items is 25)

Geo - Contains the following reservedsystemfields:

street_address

street_address2

city

state

postal_code

country

tz (time zone)

loc

lat (latitude)

lon (longitude)

Advanced: Customize Attribute Access - Provides additional control over how attributes are treated with contact deletions as well how they are updated using JavaScript listeners. Note that this functionality is for advanced usage only. Please contact your Client Success Manager before making changes. Learn more about customizing attribute access below.

Depending on the type of attribute selected, there maybe additional information required:

Searchable - Checking this box will allow the attribute to be searchable within the system and available to build audience rules.

Required - Checking this box will make the attribute value required when importing or editing contact records. Only select required if you never want to have a contact without this value. When importing, contact records that do not have this value will be rejected.

Adding attributes via CSV upload

Contact attributes can also be added to the system when importing contact records.

Prepare a CSV file where the header row contains the names of the attribute keys you would like to add to the system.

Log into the Cordial platform and navigate to Data Import Contacts

Choose the appropriate options

Import Source - Choose whetherthe source is a local or hosted file.

Header Row -Select this option if your data file contains a header row. It is recommended to have a header row to make it easier to identify and mappreexisting attribute names.

Choose Delimiter

Select and upload your CSV.

You'll then have the option to "Add Attribute" for each header row column you have created.

Note: Preexisting attributes and lists with the same name will already be mapped. If you need to map to a preexisting attribute with a different name, use the dropdown labeled "choose".

Adding attributes via API

For information about creating contact attributes via the API, read the article about Account Contact Attributes.

Using Contact Attributes in a Message

Contact attributes values can be used to personalize message using Smarty contact variables.

For example, you could display a contact's first name using the following Smarty code:

{$contact.first}

The above code assumes that the contact attribute "first" is in the system. Note that the contact attribute "first" is prepended with the word "contact" because all contact attributes are stored in the contact collection.

Using Smarty, you are able to not only display contact attributes, but also construct conditional statements that can render message content dynamically based on contact attribute values.

For more info on using contact attributes to personalize message content using Smarty, see the following articles:

Smarty contact variables

Conditional "if" statements

Note: During message creation it is useful to use the following Smarty utility to view the contact record in JSON format:

{$utils->jsonPrettyPrint($contact)}

By pasting the above code into the HTML editor and clicking the preview button, you are able to view the specified contact's record with all attributes, list association and cart items (if available).

Building Audiences Using Attributes

Using the audience builder, you can search and segment contacts based on the 4 types of contact attributes, string, number, date, geo and array.

You are able to build complex segmentation queries by combining, including and excluding audience rules and sets of audience rules with and/or operators.

In the audience builder image below, note the highlighted rules associated with contact attributes:

Learn more about the audience builder

Triggering Messages Using Attributes

With message automations you are able to trigger message sends based on the change of a contact attribute. For example, if you have a contact attribute called member level, you could trigger a message when the value for member level changes (i.e. silver to gold).

To trigger an automated message based on a change to a contact attribute, use the Event Triggered sending method, and choose the Trigger Event: "When a change is made to a contact attribute value".

Learn more about automated messages

Building Reports Using Attributes

Audiences based on contact attributes can be saved as audience rules and either visualized over time with audience trend reports or used as filters for event data dashboards and event data reports.

Audience trend reports

Using audience trend reports, you can view the population over time of an audience based on contact attributes.

For example, you could compare audiences of contacts based to their Member Level by creating 3 audiences (silver, gold, platinum), enabling audience trend analytics on each one, and viewing them on the audience trends chart.

Filtering event dashboards

Event dashboards provide a way to visualize event activity over time by creating customizable charts. You can take advantage of contact attributes in event dashboard charts using audience filters.

For example, you can create a chart that plots message activity over time filtered by a saved audience rule where the contact attribute for member level is Gold.

Filtering event data reports

Event data reports allow you to view reports of event activity. You are able to filter reports using audience rules similar to the event dashboard charts. For example you can filter by a saved audience rule where the contact attribute for member level is Gold.

Customize Attribute Access

To provide additional control for privacy compliance (i.e. GDPR ), you have the ability to customize how attributes are accessed and deleted.

Note: This functionality is for advanced usage only. Please contact your Client Success Manager before making any changes.

To configure, edit an existing attribute or create a new attribute and click the option for Advanced CustomizeAttribute Access.

Publicly editable

Selecting this option will allow unauthenticated modifications to the attribute. If you are using JavaScript listeners to automatically update the attribute, you will need to select this option. Please note that this option comes with compliance concerns as it makes it possible for malicious users to change the value.

Note: This features requires explicit consent for proper functionality. Please contact your Client Success Manager or submit a support request before making any changes.

Retain data on delete

This functionality gives you the ability to control how attribute data is treated when a contact is deleted from the system.

Destroy - This is the default option. All contact attribute data is deleted.

Anonymize - Replaces attribute data with a random value. Please contact your Client Success Manager before choosing this option.

Retain the data as is - This option keeps the attribute data. There are possible security concerns with this option. Please contact your Client Success Manager before choosing this option.

Mixing "retain data on delete" options across multiple attributes

If you choose to mix the options for retaining data across multiple attributes and then delete the contact, the following will occur:

The channels.email.address value will be anonymized.

Any attributes set to destroy will be permanently deleted.

Any attributes set to anonymize will be given a random value.

Note that the same random value will be given to anonymized attributes with identical anonymized attribute values. For example, if a contact has a value of "blue" for the anonymized attribute of eye_color it could be given a random value of "abcdefkkl" upon deletion. If multiple contacts are deleted with the anonymized eye_color attribute value of "blue", then they would also be given the same random value of "abcdefkkl".

Any attributes set to "Retain data as is" will retain their values.

The anonymized contact record with the above changes will be retained in the database.

In the next article.

In this Article

About Podium

Podium Overview

Creating a New Podium Orchestration

Defining the Trigger

Setting the Delay

Delaying Custom Event Triggered Messages

Setting the Audience Filter

Defining the Action

Adding Additional Automations

Setting the Orchestration Goal

Publish and Enable

Viewing Podium Insights

Drafts and Past Versions

About Podium

Podium orchestrations provide an easy way to create, visualize and monitor cross-channel triggered campaigns for each customer touch point.

You are able to launch multiple automations using a single trigger, making welcome, abandon, and re-engagement campaigns a breeze to set up.

Podium Insights, a set of performance metrics and indicators, will be displayed within published orchestrations, without the need to exit Podium. Immediately visible insights for each automation component include overall metrics for status, filtered and action categories, with detailed indicators coming into view upon hovering over each category.

Orchestration goals can be used to remove contacts who meet the desired goal from an orchestration based on their real-time behavior.

Orchestrations support draft, published and past versions for powerful version control.

You can add detailed descriptions to every component of the orchestration, making it easy to visualize the strategy of each automation. You are also able to print the orchestration for sharing with other team members.

Podium Overview

custom named event

Creating a New Podium Orchestration

Navigate to Message Automation -> Podium Orchestrations and click New.

Give the orchestration a name, add any tags and click Continue. You will be taken to the Podium orchestration main page. The order of operations for every automation follows exactly how components are stacked, starting with message send delay (or "Wait Until" trigger), followed by filter/audience criteria, and finally the action.If a contact is filtered out of an automation, they will be ineligible for any subsequent child automations (directly below). However, they will remain eligible for any sibling automations (directly to the right) provided they pass those filters.

Orchestration Settings

From the main orchestration page, you are able to configure the orchestration with settings defined in the table below.

Name

Description

Orchestration name

Name the orchestration

Enable/Disable

Enables or disables the orchestration. An orchestration must be published before it can be enabled. Disabling a published orchestration will stop any messages from being sent.

Save Draft

Saves an orchestration draft.

Publish

Publishes an orchestration draft. If viewing a published orchestration, there will be an option to Copy as Draft.

Version View

Displays the orchestration version view (draft, published or past versions).

Goal View

Displays the orchestration goal.

Orchestration View

Displays the orchestration view.

Trigger Component

Defines the initial trigger for the orchestration.

Trigger Options:

Contact's profile is updated, a contact's real time behavior, a date or timestamp, recurring interval.

Delay Component

Defines the delay time before contacts are sent through the automation after meeting the initial orchestration trigger.

Delay Options:

Immediate, minutes, hours or days.

Filter Component

Filters the recipients of the automation using an Audience Rule.

Action Component

Defines the action for the automation.

Action Options:

Send an email, an SMS (if enabled in the account), mobile push (if enabled in the account), a request using Open channel to a third party system(if enabled in the account) or a Data Automation job(if enabled in the account).

Wait Until Component

Defines the trigger for subsequent automations.

Trigger Options:

Do not wait, wait for previous message event (opened, clicked or bounced), wait for other event (message eventor custom named event).

Add Action

Adding an action using theplus icon below an existing automation will add a new child automation starting with the "Wait Until" trigger component. Adding an action using the plus icon to the right of an existing automation will add a new sibling auotmation starting with the "Delay" component.

Print

Prints the orchestration page.

Zoom

Zooms in or out of the orchestration.

Automation Insights

Overall performance metrics for status, filtered and action components are displayed to the right of each automation. A deeper view into these metricsbecomes visible upon hovering the desired category to display indicators.

Defining the Trigger

The first step in an orchestration is defining a trigger. Clicking on the trigger component will open a window containing trigger options:

A contact's profile is updated - triggers an orchestration based on a profile change.

A contact's real time behavior - triggers an orchestration based on an action a contact takes.

A date or timestamp - triggers an orchestration based on the proximity of a date or timestamp.

Recurring Interval - triggers an orchestration on a recurring schedule based on audience rules.

A Contact's Profile Is Updated

This trigger is used for starting orchestrations when a change is made to a contact's profile.

For example, you can start a series of automations when a contact is added to the newsletter list or when a contact's loyalty attribute is changed.

Selecting this trigger type will display options for choosing either a contact attribute or a list, with dropdown menus for all available attributes or lists in your account.

Use Case - Welcome Series

Use this trigger when setting up a welcome series. Learn more about setting up a welcome series using Podium.

A Contact's Real Time Behavior

This trigger is used for starting orchestrations based on a real-time behavior a contact makes.

For example, you can start a series of automations when a contact opens or clicks a previously sent automation, or when a contact performs a custom event (browses a page on your website, adds something to the cart, places an order, etc).

Selecting this trigger type will display a list of message events and custom named events to choose from.

Use Case - Abandon Campaign

Use this trigger when setting up an abandon cart/browse/search campaign. Learn more about setting up an abandon cart campaign using Podium.

A Date or Timestamp

This trigger is used for starting orchestrations based on a date.

For example, you can start a series of automations based on birthdate, an anniversary, an expiration, etc.

Selecting this trigger will display a list of system dates and custom dates to choose from.

Note: Date or Timestamp triggers will only count as triggered if the contact meets both the trigger rule AND the audience filter.

Use Case - Expiration Notification

Use this trigger when setting up an expiration campaign such as when a contact's membership is about to expire.

Recurring Interval

This trigger is used for starting orchestrations automatically based on a recurring schedule and a set of audience rules. With all of the Audience Builder rules at your disposal, the potential use cases are near limitless.

Note: Please contact your CSM for details about enabling the Recurring Interval trigger for your account.

Sending Interval - Schedule recurring sends to occur every day, week or month. If weekly or monthly, specify day of the week or date in a month.

At what time - Choose the send time and time zone.

Start date - Specify recurring send start date.

Add end date (optional) - Specify recurring send end date.

Use Case - Win-Back Campaign

Use this trigger when setting up a retargeting campaign for contacts who have not opened a specific message within a defined period of time.

For example, using the Recurring Interval we can set up a win-back campaign to automatically retarget an audience segment that has not opened the monthly clearance sale message within 15 days of message send time.

Recurring Trigger Notes:

Recurring triggers are always followed by a single Action component.

Additional sibling action components can be added parallel to one another.

A full automation consisting of Wait Until, Delay, Filter, and Action components can be added below the initial action component(s).

Setting the Delay

Once the trigger is defined, you have the option to set a delay before the automation is sent.

The delay may be set as immediate (no delay) or a specified number of minutes, hours or days. A delay cannot be set for orchestrations using a data/timestamp trigger. The delay component will be greyed-out being that the automation will trigger immediately based on the desired date or timestamp trigger.

Note: The delay period will not reset when an orchestration is copied to draft and republished unless manually changed to a new value. Rather, the delay timer will resume where it left off just before the orchestration was copied to draft.

Delaying Custom Event Triggered Messages

Unlike immediate sending, delayed sending presents an opportunity for the contact to trigger custom events more than once during the delay and before the message is sent. This is especially true when the trigger is based on custom events such as browse, product view, add to cart, etc.

Settings for handling events triggered during delay will become available in the Delay component when the orchestration trigger is based on a custom event.

Use Case - Browse Abandonment

Your contact may be interested in a particular jacket on your website. They view the product page but leave without making a purchase. You are able to send them a follow-up message based on this activity after a specified period of time.

The best suited orchestration trigger for this use case is A contact’s real time behavior based on a custom event we created and named browse_product.

Conditional event properties allow you to consider only those browse events that match specific criteria, in this case, when the product name is Cordial Blue Jacket.

Available orchestration trigger frequency options include:

Once only - Contact can trigger this orchestration one time.

Unlimited - There is no limit to how many times contact can trigger this orchestration.

Once an hour - Contact can trigger this orchestration once every hour.

Once a day - Contact can trigger this orchestration once per day.

Custom interval - Specify the number of times contact can trigger this orchestration per number of days or hours.

Once the trigger is configured, opening the Delay component will now reveal If/Then conditions for handling of contact activities, or events, while the delay timer counts down.

In our example, the initial If condition will auto-populate with the browse_product custom event that is set as the orchestration trigger.

The Then statement can be configured to handle recurring custom event triggers according to the following options:

Fire a unique action each time - Send a message for every occurrence of the custom event trigger within the specified delay time. For example, if the delay is set for 10 minutes, a contact who triggers the custom event at 3:00 PM, and again at 3:09 PM, will receive two messages, one at 3:10 PM and another at 3:19 PM.

Note: The trigger frequency determines how many times the orchestration can be triggered by a contact. If set to Once only, the Fire a unique action each time option will not be applicable, since the custom event can be triggered no more than once. In the example above, the trigger frequency is set to Unlimited to compliment sending multiple messages any time the custom event is triggered during the delay.

Continue the delay time - Delay timer will be unaffected by subsequent custom event triggers. For example, the first browse_product event could be triggered at 3:00 PM, and a subsequent one at 3:04 PM. Because subsequent triggers are ignored, only one message is sent at 3:10 PM.

Restart Delay time - The delay timer will restart from the beginning each time the custom event occurs until it is allowed to expire in absence of repeated triggers.

Multiple If/Then conditions can be added to further automate message sending based on contact's real-time behavior.

Setting the Audience Filter

The audience filter allows you to filter the recipients of the automation by an Audience Rule. You are able to set up a new audience or load a saved audience.

Defining the Action

The last component in an automation is the action. Clicking on the action component will open a window containing the three action options:

Send an email - sends contacts an automated email message.

Send an SMS (if enabled in the account) - sends contacts an automated SMS message.

Send a push notification (if enabled in the account) - sends contacts an automated push message.

Make an Open channel request (if enabled in the account) -makes a RESTful API call to a specified endpoint.

Run a Data Automation job (if enabled in the account) - runs a data job to transform the collection data specified.

Message Creation

Clicking on either of the above Action options will open up the automated message creation page. You are able to use either the Sculpt or HTML editor to compose message content.

You will have access to the same message creation features and functionality found in other automated messages, except the ability to edit the sending method.

Note: Automated messages created in Podium can only be viewed and edited within the orchestration. Podium automations are not accessible outside of Podium.

Adding Additional Automations

Podium supports multiple automations in a single orchestration. Clicking the Plus button will add an additional automation either next to (sibling) or below (child) the current automation.

If an automation is added below, there will be an option to set an additional trigger: Wait Until.

You have the options for Do not wait, wait for previous message events (opened, clicked or bounced) or wait for other event ( message event or ) before the automation will send.

Setting the Orchestration Goal

The orchestration goal is used to set a primary objective for the orchestration. This objective is defined by a custom event such as "placed an order", "viewed a webpage", etc. When contacts complete the objective, they can be excluded from, or continue through, the remaining actions within the orchestration. Note that the orchestration goal is optional and not required before an orchestration can be published and enabled.

Clicking on the Goal icon will display options to set a goal for the orchestration. Give the goal a name, select a custom named event and define what happens to a contact when the goal is met. There are options to keep or exclude the contact from an orchestration.

Adding Descriptions and Printing

When a component is configured, a default description is added. You can easily edit the description by clicking and typing text in the description field.

You can zoom in or out of an orchestration and print for sharing with other team members.

Publish and Enable

Once all components are configured and message content is created, you can publish the entire orchestration by clicking the Publish Draft button.

If any components are left incomplete, you will see an error with the incomplete components highlighted.

After successfully publishing the orchestration, you can enable it using the Enable/Disable dropdown.In the published state, the delay, filter and action components are read-only until the orchestration is copied to draft.

When an orchestration is running and then disabled, all message sending will be stopped for that orchestration, even if the contact is in the delayed state. Once the orchestration is enabled again, contacts will continue on the path from their last state, andall updates to Podium insights will resume.

Viewing Podium Insights

Podium Insights are available for the entire orchestration and for every automation within the orchestration. Once an orchestration is published, enabled and sending, you can gain insight into its performance all the way down to individual automation components.

Goal performance will be displayed at the top of the orchestration page. Results can be viewed as total or unique values and applied to the current version only, or aggregates, which includes past versions of the orchestration.

Total/Unique Triggered - total or unique number of contacts that triggered the orchestration

Current Version - display results for the currently published version only

Aggregates - display results for all versions of the orchestration, current and past

Component summary metrics will be displayed to the right of individual automations. Hovering over each category (status, filtered, action) will display detailed indicators.

Waiting - number of contacts waiting to be triggered according to to the Wait until trigger

Delayed - number of triggered contacts in the delayed state

Filtered Out - number of contacts that didn't meet the audience criteria and were filtered out of the automation

Note that tracked indicators for the Action component differ depending on the channel used to send the message.

Email Sent - number of contacts that received the email message

SMS Sent - (if enabled in the account) number of contacts that received the SMS message

Push Sent - (if enabled in the account) number of contacts that received the push message

If viewing Podium Insights forpast orchestration versions, you will see all campaign metrics up until the point that version was re-published.

Drafts and Past Versions

Copying to draft provides an easy way to modify all aspects of the orchestration. When an enabled orchestration is copied to draft, the live published version will continue to run until the new draft is republished.

Note: When a draft orchestration is republished, existing Podium Insights will not be affected, unless the orchestration contains one or more experiments, in which case, republishing would reset all Podium Insights.

All previously published versions will be saved under the Past Versions tab. Past versions are saved using the orchestration published date and time stamp. The orchestration enabled date is not displayed in this view.

When copying to draft and adding a new action, the contact that received the initial message will need to re-trigger the orchestration to receive messages created with the new action, assuming the contact met the audience criteria and were not filtered out.

In This Article

Overview

Setting Up up Multi-Factor Authentication

Multi-Factor Authentication Status

Reset Multi-Factor Authentication

Overview

Multi-Factor Authentication, or MFA for short, is a method of granting account access using more than one authentication method. For instance, instead of merely keying a password to log into an account, MFA might require a verification code sent through SMS or a third-party app to be entered as well.

Based on your company's security policies, MFA can be activated for your users so that each time they log in they are required to enter their MFA token in addition to using the password.

Note: Admin level user permissions are required to access and modify MFA settings.

Setting up Multi-Factor Authentication

Log into your Cordial account and navigate toAccount & Password using the top right navigation menu.

submit a ticket

Under Multi factor authentication, click theEnable button.

Next, open your MFA app. If you do not already have one, download the Google Authenticator App from the Google Play Store or the Apple App Store. Use the Google Authenticator app to scan the QR code or enter the written code into the Enter code from device field.

Moving forward, whenever you log into your Cordial account, you will be prompted to enter your password along with the authentication code provided in your MFA app.

Multi-Factor Authentication Status

You can view the MFA status of all of your users by navigating to Users from the top right navigation menu.

Reset Multi-Factor Authentication

To reset MFA for a user, please . Be sure to specify which username (i.e., email address) needs its MFA reset.

In This Article

Overview

Batch Message Video

Creating a New Message

Scheduling the Message

Building an Audience

Creating the Message Content

Configuring Goals and Tracking

Selecting the Message Transport

Sending a Test Message

Sending the Message

Viewing and Searching Sent Messages

Overview

Batch messages are used for one time sends. They can be sent immediately or scheduled for a future date.

Batch messages can be sent through any available channel: email, SMS and mobile push.

Batch Message Video

This video shows you how to create a batch message.

learn about scheduling and throttling a message send

Creating a New Message

When creating a new batch message you will need to give the message a name, add any message tags and choose the sending channel.

Navigate to Messages Create New Message

Complete new message info:

Message name - The name that will be referenced in the system.

Tags - Tags are used for grouping related messages, searching and building audiences and filtering message reports.

Channel - The channel will affect the type of message being sent - email, SMS, or mobile push. This selection will affect the message content method as well as the transport.

Scheduling a Message

Batch messages can be sent immediately or scheduled for a future date. When scheduling for a future date, you have the option of scheduling according to the contact's time zone.

Message sending can also be throttled so messages go out in batches according to audience size or max number of batches. This is useful when you are switching from another ESP and need to warm the new IP address for improved deliverability. Learn more about IP ramping.

Messages will send immediately by default. To edit the schedule, click the Edit button under Schedule and choose a schedule option:

Send immediately

Schedule for future date

Throttled batch sending

Learn more about scheduling and throttling messages

Building an Audience

Before a message is sent you must choose the audience to send to. You have the option to send to all contacts or use the audience builder to filter your contacts according to include and exclude audience rules.

Learn more about the audience builder

Creating the Message Content

The type of message content will depend on which channel you choose to send the message. If choosing the email channel, you must also fill out Message Header info that includes the subject, the from email, the reply email and the fromdescription.

View the following articles to learn about creating content for the different message channels:

Create message content for the email channel

Create message content for the mobile push channel

Configuring Goals and Tracking

Choose whether to enable or disable link tracking for all links in the message. This only applys to the email channel. You are able to disable link tracking on individual links using Smarty.

Note: All event activity is stored in Cordial for 18 months. Message opens and clicks are tracked for 30 days from the time of a message send, after which tracked links will expire. You are able to request a default URL (such as a home page) for expired tracked links by contacting your Client Success Manager.

Selecting the Message Transport

The message transport only applies to the email channel.

During account creation, your account is set up with one or more email sending transports. If your account has multiple sending transports, you will have the option to choose the transport for the message.

Note: To maintain healthy delivery, be sure to choose the sending transport that matches the message classification (promotional or transactional).

Sending a Test Message

You are able to send a test message in order to check rendering in the inbox. Before a test message can be sent, the message headers and message content must be provided.

Enter Contacts: Type or paste one or more email addresses separated by commas. Convenient for sending test messages to frequently used test accounts.

Search and select contacts: Search for contacts by keyword. Useful for retrieving a list of contacts that match your criteria such as those that have your email domain @yourdomain.com.

When ready, click the Send Test Now button.

Note: All test email addresses must exist as valid and subscribed contacts in your account.

Note: Test message links will expire after 24 hours if link tracking is enabled for the message.

Note: If you are receiving the error "Internal Render Error", when trying to send test messages, it may be a result of badly formed links in your HTML. Be sure to check all links for any unnecessary spaces or characters in your urls. The Internal Render Error can also be the result of a missing html include. Be sure all html includes that are referenced in a message do in fact exist in the account.

Tip: When sending multiple message tests, it is sometimes useful to have a unique subject line per send as some email clients will group all messages with the same subject line within a message thread (gmail for example). You can use the following getNow Smarty utility to generate a unique subject line per test send:

{$utils->getNow('America/Los_Angeles', "Y-m-d H:i:s")} This is a subject line

Learn more about date and timestamp variables.

Sending the Message

Once all required content has been completed, you are able to send the message to the audience specified by clicking the Send Message or Schedule Message button.

Once a message has been sent you can pause, resume or cancel a message send.

Viewing and Searching Sent Messages

After a message has been sent you are able to view it on the Sent Messages page.

By default, messages are sorted by Send Time. You can also sort messages by Name by clicking its column header in the sent messages table.

Searching Sent Messages

You can quickly search a message by name using the search field at the top of the page.

Additional search and filter functionality is available in the Advanced Search menu.

Search by Tag

Use the Tags search input to search any messages that contain specified tags. To search multiple tags, use a comma to separate each tag. The comma acts as an "or" operator.

Filter by Send Time

Using the Send Time search input, you can filter messages that were sent On, Before, or After a specified date.

Filter by Status

Using the Status dropdown, you can view messages with a sending status of Sent, Cancel, Pause or Sending.

Filter by Feature

You can display messages that contain specific features usingFilters. Select the checkboxes to filter sent messages that have an Inbox Placement Test, a Throttled send, Timezone sending or an Experiment.

In the next article.

In this Article

Overview

Automation Overview Video

Creating an Automation

Creating Message Content

Send a Test

Publishing Message

Enabling the Sending Method

Configuring the Message Settings

Overview

Automated messages are used for triggering message sends by one of the available sending methods:

API - Send is triggered by a POST /automationtemplates API call.

Event Triggered -Send is triggered as the result of a contact's behavior or a change to a contact's attribute.

Recurring Schedule - Send is triggered according to a recurring date or time interval.

Any of the above sending methods can be filtered by audience rules.

Automation Overview Video

learn about content versioning

Creating an Automation

Navigate to Message Automation Create New Automation.

Fill out the fields to create a new automated message.

Message name - The friendly name that will be referenced in the system.

Message key - The name used to reference the message in the database for API calls. Message keys are not generated for batch messages.

Tags - Tags are useful for grouping messages together (similar to folders) when building audiences and filtering message reports.

Classification - Give the message a classification to comply with SPAM laws.

Promotional - For subscribers that gave permission to receive a promotional message. Note that promotional messages will only be sent to contacts that are both valid and have a subscribe status of subscribed.

Transactional - For subscribers that are receiving the message based on an order. Transactional messages can be sent to anyone who is valid regardless of their subscribe status. This classification is not available for SMS and Push automated messages.

Note:

If your account has multiple sending transports, be sure to choose the appropriate transport for the designated message classification.

Transactional classification should only be set when you are certain the message meets your local legislation for what is defined as a transactional message.

Channels - Choose the supported channel to send the message. Automated messages currently support email, SMS and mobile push channels.

Creating Message Content

The message content requirements will differ depending on the selected channel. The following articles provide more information about creating message content for the available message channels:

Create message content for the email channel

Create message content for the SMS channel

Create message content for the mobile push channel

Send a Test

You are able to send a test message in order to check rendering in the inbox. Before a test message can be sent, the message headers and message content must be provided.

Enter Contacts: Type or paste one or more email addresses separated by commas. Convenient for sending test messages to frequently used test accounts.

Search and select contacts: Search for contacts by keyword. Useful for retrieving a list of contacts that match your criteria such as those that have your email domain @yourdomain.com.

When ready, click the Send Test Now button.

Note: All test email addresses must exist as valid and subscribed contacts in your account.

Note: Test message links will expire after 24 hours if link tracking is enabled for the message.

Note: If you are receiving the error "Internal Render Error" when trying to send test messages, it may be a result of badly formed links in your HTML. Be sure to check all links for any unnecessary spaces or characters in your URLs.

Tip: When sending multiple message tests, it is useful to have a unique subject line for each send, as some email clients will group all messages with the same subject line within a message thread (gmail for example). This could make it difficult for your contacts to see new messages immediately.

You can use the following getNow Smarty utility to generate a unique subject line per test send:

{$utils->getNow('America/Los_Angeles', "Y-m-d H:i:s")} This is a subject line

Learn more about date and timestamp variables.

Publish the Message

Before a message is published, it is labeled as a draft message and sending methods will be disabled.

After completing the message headers and message content, the message can be published by clicking the Publish button.

The published message is the "live" version that will be sent when a sending message trigger is met.

You are able to work on another draft and send tests without affecting the published version. Once you are happy with the draft, you can click Publish. The current published version will then be saved to the Past Versions tab and available for recall.

Learn more about content versioning.

Enable the Sending Method

The sending method determines how the message will be sent. There are 3 sending methods:

API - messages that are send via an API call.

Event Triggered - messages that are sent froma event trigger.

Recurring - messages that are sent on a recurring basis.

Learn more about sending methods.

Configure Message Settings

Under the settings section you can configure settings for Goals and Tracking as well as Delivery Settings.

Goals and Tracking

Stats Aggregation

Choose whether the aggregate message performance stats will be rolled up daily or hourly. After a message has been sent you can view message aggregate performance under the Message Performance tab.

Note: Options for daily and hourly stats aggregation can only be selected for Event and API Triggered message sends. Recurring message stats are always aggregated at the scheduled interval.

Link Tracking

Choose whether to enable or disable link tracking for all links in the message. You are able to disable link tracking on individual links using Smarty.

Note: All event activity is stored in Cordial for 18 months. Message opens and clicks are tracked for 30 days from the time of a message send, after which tracked links will expire. You are able to request a default URL (such as a home page) for expired tracked links by contacting your client success manager.

Delivery Settings

During account creation, your account is set up with a sending transport. If your account has multiple sending transports, you will have the option to choose the transport for the message. To maintain healthy delivery, be sure to choose the sending transport that matches the classification that you set for the message (promotional or transactional).

In the next article.

In This Article

Overview

Summary Performance

Stats Filters

Audience rule filter

Send tag filter

Inbox Placement Test

Link Performance

Time of Day Analysis

Overview

The Message performance page will give you an overview of how a sent batch message performed.

To view the batch message performance page, select the desired message in the Sent Messages list. You can also access the message performance page by clicking on the Performance tab on the sent message summary page.

learn about pausing and canceling a message send

Summary Performance

The summary performance report provides the following KPIs:

Sent

Total messages sent

Delivered

Percentage = (sent - bounced) / sent

Total delivered

Bounced

Percentage = bounced / sent

Total bounced

Opened

Percentage = unique opens / delivered

Unique

Total

Clicked

CTOR Percentage = unique clicks / unique opens

Unique

Total

Click rate percentage

Opt Outs

Percentage = total opt outs / delivered

Total

Complaints

Percentage = total complaints / delivered

Total

Stats Filters

Stats filters provide a way to further filter your message stats using audience rules and send tags.

To enable this feature in your account, please contact your Client Sucess Manager.

Audience rule filter

By applying an audience filter to the report, you can view a subset of the total message stats.

For example, you can filter message stats according to gender to compare how males and females performed against the entire message send. Before adding the filters, the desired audience rules must already exist in the system.

To add audience rule filters:

Click the Filter by audience rule button.

Choose a previously saved audience rule and click continue.

Each additional audience rule will show on a new row with the appropriate stats.

Note: Audience rule results are dynamic and may change over time. This may skew stats and show different results depending on when the message was sent. To maintain consistent results, use send tag filters.

Send tag filter

To maintain consistent stats filter results over time you can apply send tag filters. Send tag filters are added within the message code using Smarty, and can be unique per contact based on a contact's attribute.

Note: Ensure that tags added using the addSendTag utility are not duplicates of tags added during message creation. When duplicate tags are present, only one instance will be tracked.

For example, you may want to filter message stats according to a loyalty attribute to check a subset of the message send stats for Gold, Silver and Platinum members.

To add send tag filters:

Add the Smarty code to the message content to generate the tag on message send. In the loyalty example, we would use the following Smarty code assuming the contact attribute loyalty exists in the system.

{$utils->addSendTag($contact.loyalty)}

The above code will add the send tag with contact's loyalty value per each message.

Open the sent message and choose Filter by tag under Stats Filters.

Choose the desired tags. In this example, silver, gold or platinum.

Repeat the process for all desired tags and view the results.

Inbox Placement Test

Inbox placement results will only be shown if enabled in the account.

Learn more about inbox placement tests.

Link Performance

The Link Performance section allows you to visualize link performance across desktop, tablet and mobile devices for:

Average clicks

CTOR

Total clicks

Unique clicks

Tracked links will display as URLs unless they are named using Smarty within the message content. Learn more about naming tracked links.

Link performance results can be exported into a CSV file. ClickExportto download the results locally.

Note: All event activity is stored in Cordial for 18 months. Message opens and clicks are tracked for 30 days from the time of a message send, after which tracked links will expire. You are able to request a default URL (such as a home page) for expired tracked links by contacting your Client Success Manager.

Time of Day Analysis

Time of Day Analysis allows you to visualize opens and clicks for the past 30 or 90 days on desktop, tablet or mobile devices.

In the next article .

In This Article

Overview

Summary Performance

Stats Filters

Audience rule filter

Send tag filter

Link Performance

Time of Day Analysis

Overview

Automated message performance gives you an overview of how a message performed. You can view stats as an aggregate of all messages or per message sent.

You can view message performance by opening an automated message and selecting either Sent or Aggregates under message performance.

Learn more about naming tracked links

Aggregate totals can be rolled up daily or hourly. This can be configured on the Goals & Tracking tab, under Settings per each automated message.

Summary Performance

The summary performance report provides the following KPIs:

Sent

Total messages sent

Delivered

Percentage = (sent - bounced) / sent

Total delivered

Bounced

Percentage = bounced / sent

Total bounced

Opened

Percentage = unique opens / delivered

Unique

Total

Clicked

CTOR Percentage = unique clicks / unique opens

Unique

Total

Click rate percentage

Opt Outs

Percentage = total opt outs / delivered

Total

Complaints

Percentage

Total

Stats Filters

Stats filters (not available on aggregate reports) provide a way to further filter your message stats using audience rules and send tags.

To enable this feature in your account, please contact your Client Sucess Manager.

Audience rule filter

By applying an audience filter to the report, you can view a subset of the total message stats.

For example, you can filter message stats according to gender to compare how males and females performed against the entire message send. Before adding the filters, the desired audience rules must already exist in the system.

To add audience rule filters:

Click the Filter by audience rule button.

Choose a previously saved audience rule and click continue.

Each additional audience rule will show on a new row with the appropriate stats.

Note: Audience rule results are dynamic and may change over time. This may skew stats and show different results depending on when the message was sent. To maintain consistent results, use send tag filters.

Send tag filter

To maintain consistent stats filter results over time you can apply send tag filters. Send tag filters are added within the message code using Smarty and can be unique per contact based on a contact's attribute.

Note: Ensure that tags added using the addSendTag utility are not duplicates of tags added during message creation. When duplicate tags are present, only one instance will be tracked.

For example, you may want to filter message stats according to a loyalty attribute to check a subset of the message send stats for Gold, Silver and Platinum members.

To add send tag filters:

Add the Smarty code to the message content to generate the tag on message send.

In the loyalty example, we would use the following Smarty assuming the contact attribute "loyalty" exists in the system.

{$utils->addSendTag($contact.loyalty)}

The above code will add the send tag with contact's loyalty value per each message.

Open the sent message and choose Filter by tag under Stats Filters.

Choose the desired tags. In this example, silver, gold or platinum.

Repeat the process for all desired tags and view the results.

Link Performance

Allows you to visualize link performance (not available on aggregate reports) across desktop, tablet and mobile devices for:

Average clicks

CTOR

Total clicks

Unique clicks

Tracked links will display as URLs unless they are named using Smarty within the message content. .

Link performance results for sent messages can be exported into a CSV file. ClickExportto download the results locally. Link performance results are not available as aggregates for all versions of sent messages.

Note: All event activity is stored in Cordial for 18 months. Message opens and clicks are tracked for 30 days from the time of a message send, after which tracked links will expire. You are able to request a default URL (such as a home page) for expired tracked links by contacting your Client Success Manager.

Time of day analysis

Allows you to visualize time of day analysis for opens and clicks for the past 30 or 90 days on desktop, tablet or mobile devices.

Aggregate reports also provide the option to select the day of the week the email was sent.

The data stored within a supplement can be referenced and used within any message body.

Our Example

The getRecords Method

How to set the key

How to set the query

How to set the limit

How to sort the data

How to set the cacheMinutes

Rendering the data in a message

Looping through data with {foreach}

Referencing an index of the array

Using Smarty variables in supplements

Our Example

For our example we'll be using supplement data consisting of a list of automobiles.

Using the tabs below you can view the HTML and Smarty used in the message, the supplement data being referenced (in JSON format) and the rendered output that will display when a message is sent or previewed.

Try it out: Download the sample data in .csv format and use the API to upload into your system for testing.

Learn more about uploading supplement records.

HTML & Smarty

Supplement Data

Rendered Output

{$cars=$supplements->getRecords('automobiles')}

{foreach $cars as $car}

<strong>{$car.brand|capitalize} {$car.model|capitalize}</strong><br>

${$car.price}<br>

Mileage: {$car.mileage}<br> <br>

{/foreach}

[

{

"model": "pilot",

"brand": "honda",

"price": 33000,

"mileage": 100000,

"id": "01"

},

{

"model": "explorer",

"brand": "ford",

"price": 34000,

"mileage": 39000,

"id": "02"

},

{

"model": "prius",

"brand": "toyota",

"price": 27000,

"mileage": 66000,

"id": "03"

},

{

"model": "model s",

"brand": "tesla",

"price": 130000,

"mileage": 56000,

"id": "04"

},

{

"model": "versa",

"brand": "nissan",

"price": 16000,

"mileage": 94000,

"id": "05"

},

{

"model": "camary",

"brand": "toyota",

"price": 29000,

"mileage": 310000,

"id": "06"

},

{

"model": "accord",

"brand": "honda",

"price": 24000,

"mileage": 49000,

"id": "07"

}

]

Honda Pilot

$33000

Mileage: 100000

View details

Ford Explorer

$34000

Mileage: 39000

View details

Toyota Prius

$27000

Mileage: 66000

View details

Tesla Model S

$130000

Mileage: 56000

View details

Nissan Versa

$16000

Mileage: 94000

View details

Toyota Camary

$29000

Mileage: 310000

View details

Honda Accord

$24000

Mileage: 49000

View details

The getRecords Method

In order to access supplement data within a message, use the getRecords method, a custom extension of Smarty provided by Cordial.

The getRecords method has 5 parameters: key, query, limit, sort and cacheMinutes. They must be written in this order and separated by commas. Only "key" is required. If you would like to leave a preceding parameter blank, it must be populated by either empty brackets "[]" for arrays or the word "null" for integers (empty single quotes should also work for integers).

getRecords($key, $query, $limit, $sort,$cacheMinutes)

Parameters

Description

Required

Expected

Default

key

A unique key created by the user for a stored supplement.

Required

Valid key

NA

query

A filter used to limit the data set. Only indexed fields can be queried.

Optional

Array

[]

limit

A filter that sets a maximum number of records to return.

Optional

Integer

25

sort

Sort the order of the records returned. ASC (ascending), DESC (descending), LM (last modified), CT (created).

Optional

Array

[]

cacheMinutes

Number of minutes to store the feed data in memory. This optimizes send time if the system doesn't have to request the feed for every individual message.

Optional

Integer

0

How to set the key

A unique key is created with each new supplement and is used to identify the supplement in the database. Learn how to create a supplement.

You can retrieve the supplement key 2 ways:

Via the UI by navigating to Data Supplement Data

Via the API by using the GET <path>/supplements call. View the interactive API documentation.

Here is an example using the supplement "automobiles":

{$cars=$supplements->getRecords('automobiles')}

In the example above, a variable "cars" is assigned to the resulting data set returned from the supplement with the key of "automobiles". The getRecords method will get the data from "automobiles" for each message that is rendered per contact.

How to set the query

In some cases, you may want to get specific records from the supplement. You can achieve this by adding query filters.

Note: Only indexed fields within supplements can be used for query filters.

Return records filtered by a specified value.

["key"=>"value"]

The following example will return records where the brand is toyota:

{$supplement_record.key = "automobiles"}

{$supplement_record.query = ["brand"=>"toyota"]}

{$cars = $supplements->getRecords($supplement_record.key, $supplement_record.query)}

Return records filtered by multiple specified values.

["key"=>"value", "key2"=>"value2"]

The following example will return records where the brand is toyota AND the price is 33000.

{$cars=$supplements->getRecords('automobiles',["brand"=>"toyota","price"=>"33000"])}

Return records filtered by multiple specified values of the same key.

["key"=>["in" => [value1,value2]]]

The following example will return records where the brand is toyota OR honda.

{$cars=$supplements->getRecords('automobiles',["brand"=>["in" => [toyota,honda]]])}

The following example will return records that are not in the specified array.

{$cars=$supplements->getRecords('automobiles',["brand"=>["notIn" => [toyota,honda]]])}

Return records filtered by values that are contained in an array.

[key => ['array_contains' => "value"]])}

The following example will return records where the color black is contained in the array with the key of colors:

{$cars=$supplements->getRecords('automobiles',['colors' => ['array_contains' => "black"]])}

Return records filtered by a contact's attribute.

["key"=>{$variable}]

Example:

{$cars=$supplements->getRecords('automobiles',["brand"=>{$contact.favCarBrand}])}

Return records filtered by comparison operators.

Use a comparison operator to filter results ("lt" = less than, "gt" = greater than, "gte" = greater than or equal to).

["key"=>["lt"=>number]]

["key"=>["gt"=>number]]

["key"=>["gte"=>number]]

Example:

{$cars=$supplements->getRecords('automobiles',["price"=>["lt"=>30000]])}

{$cars=$supplements->getRecords('automobiles',["mileage"=>["gt"=>20000]])}

{$cars=$supplements->getRecords('automobiles',["mileage"=>["gte"=>50000]])}

Return records filtered by values between two numbers.

["key"=>["between"=>["start"=>number,"end"=>number]]]

Example:

{$cars=$supplements->getRecords('automobiles',["price"=>["between"=>["start"=>10000,"end"=>50000]]])}

Return records filtered by the current date/time.

["key"=>["eq"=>{$smarty.now|date_format}]]

Return records filtered by values between two dates.

["key"=>["lt"=>{$smarty.now|date_format}],"date_end"=>["gt"=>{$smarty.now|date_format}]]

How to set the limit

Use the limit filter to limit the number of records returned.

Example without a query filter and a limit of 5 records:

{$cars=$supplements->getRecords('automobiles',[],5)}

Note: If an array parameter is left empty (query in this example) be sure to leave a placeholder of empty brackets "[]".

Example with a query filter and a limit of 7 records:

{$cars=$supplements->getRecords('automobiles',["brand"=>"toyota"],7)}

How to sort the data

Sort results by price in ascending order.

{$cars=$supplements->getRecords('automobiles',[],null,['column'=>'price','direction'=>'ASC'])}

Sort results by price in descending order.

{$cars=$supplements->getRecords('automobiles',[],null,['column'=>'price','direction'=>'DESC'])}

Sort results by last modified in descending order.

{$cars=$supplements->getRecords('automobiles',[],null,['column'=>'lm','direction'=>'DESC'])}

Sort results by date created in descending order.

{$cars=$supplements->getRecords('automobiles',[],null,['column'=>'ct','direction'=>'DESC'])}

Note: If an integer parameter is left empty (limit in this example) be sure to leave a placeholder of the word "null" or an error will result. Empty single quotes is also a valid entry.

How to set the cacheMinutes

A cache can be set in memory for the data so the system doesn't have to retrieve data directly from the database for every individual message. Retrieving data from the cache instead optimizes the time it takes to compile and send messages.

You can specify the number of minutes that data is stored in memory with this parameter. The length of time data should be cached depends on how often your supplement data changes. If, for example, your supplement data doesn't change much within a short period of time, you could set cacheMinutes at 20 minutes.

{$cars=$supplements->getRecords('automobiles',[],null,[],20)}

Rendering the data in a message

After the data is available with the getRecords method, you can render the data in the message.

Looping through data with {foreach}

A {foreach} statement is the most common way to loop through the data array and render the results in a message.

Example:

{$cars=$supplements->getRecords('automobiles')}

{foreach $cars as $car}

<strong>{$car.brand|capitalize} {$car.model|capitalize}</strong><br>

${$car.price}<br>

Mileage: {$car.mileage}<br>

<a href="http://example.com/cars/{$carObject.id}">View details</a><br><br>

{/foreach}

Learn more about using the {foreach} statement.

Referencing an index of the array

If you don't need to loop through all of the data in the array, you can render a specific value by referencing its index within the array.

Example:

{$cars=$supplements->getRecords('automobiles')}

{$cars[0].brand}

Alternate syntax:

{$cars=$supplements->getRecords('automobiles')}

{$cars.0.brand}

This example will look in the first record of the data array and render the value for "brand".

Note: The 1st item of an array is referenced by "0", the second is "1", the third is "2", etc.

Using Smarty variables in supplements

Smarty variables stored within supplements will not render in a message due to the way Smarty is processed. As a workaround, you can create a placeholder in the supplement data and then use the Smarty replace function to replace the placeholder with the desired variable.

Example:

HTML & Smarty

Supplement Data

Rendered Output

{$content=$supplements->getRecords('message_content')}

{$content.0.subject = $content.0.subject|replace:'\%first_name\%':$contact.first_name}

{$content.0.subject}

[

{

"subject": "Special offer for you \%first_name\%!",

"ct": "2017-10-10T22:21:18+0000",

"lm": "2017-10-10T22:21:18+0000",

"id": "1"

}

]

Special offer for you Fred!

API Set Name: orders

POST /orders

GET /orders

GET /orders/{id}

PUT /orders/{id}

DELETE /orders/{id}

API Description and Functional Purpose

The orders collection contains all order data related to a purchase event. It is a separate collection designed specifically to accommodate data associated with orders. The most common order related attributes are provided by default as part of the schema.

Related Collections:

The following collections are associated with the Orders collection.

Collection

Association

products

A product record will be created or updated in the products collection each time an order is placed.

POST /orders

Method

URI Path

POST

/orders

Creates a new order in the Cordial database using the appropriate JSON body.

An order can include one or more items. Posting more than one time for the same orderID name will generate an error.

Parameters

* Required

Parameter

Type

Description

Example

Order

*cID or email

string or email

Cordial contactID, or the primary key which is email by default.

54b0143f9e6f974f1e98ba19 or [email protected]

*orderID

string

Unique identifier assigned for the order.

33451

*purchaseDate

string

A date value signifying the purchase data and time. Date format is ISO 8601.

2018-01-09T22:47:12+0000

mcID

string

Cordial ID that represents the account, contact and the message. Required to track revenue attribution to an email.

45:55....aef:1

linkID

string

Cordial ID that represents the message and link. Required to track revenue attribution to a specific link.

45:55....aef:1

customerID

string

An ID value assigned by the ecommerce or CRM system.

abc123

totalAmount

float

Auto-calculated as the sum of each item.amount.

235.99

tax

float

The amount of the tax.

22.50

shippingAndHandling

float

The amount charged for shipping an handling.

0.0

shippingAddress

object

name, address, city, state, postalCode, country.

see below

billingAddress

object

name, address, city, state, postalCode, country.

see below

properties

object

Key value pairs describing the properties of the order.

"currency": "USD"

*items

array of objects

Each object describes an item of the order.

See parameters per item object below

Parameters per each item object

*productID

string

A unique identifier for the product.

1234abcd

*sku

string

The Stock Keeping Unit value for a particular item.

RF-WP33286-21

*category

string

The category given to the particular item.

Major Appliance

*name

string

The name of the product.

S22-Refrigerator

qty

integer

The number of items purchased. Defaults to 1 if not passed.

2

itemPrice

float

The item price.

29.95

amount

float

Auto calculated as qty x itemPrice. If a value not equal to qty x itemPrice is passed, it will be overwritten.

59.90

description

string

Description of the product.

Great product!

url

string

Link to the product.

http://myproduct.com

images

array

A comma separated array of image file locations. Use an empty array [] as default if no values exist.

"http://example.com/image1.jpg", "http://example.com/image2.jpg"

attr

object

Key value pairs describing attributes of the product. Values added cannot be searched using the Audience Builder or within Smarty for personalization.

"size":"large",

"color":"red"

properties

object

Can be used in place of the attr key.Values added can be searched using the Audience Builder and within Smarty for personalization, ifsearching of nested order properties is enabled in the account.

"size":"large",

"color":"red"

properties

object

Key value pairs describing the properties of the order items.

"brands":["Marmot", "Quicksilver"], "return_date": "2018-07-01 00:00:00"

tags

array

A comma separated array of values to describe the product. Only accepts alphanumeric characters or dashes.

"office","office-supplies"

Optional Parameters for billingAddress and shippingAddress objects

name

string

The name of the person or company making the order.

Mark Smith

address

string

Defines the street address.

13130 Silverlake Road

city

string

Defines the city.

Hollywood

state

string

Defines the state.

CA

postalCode

integer

Defines the postal code.

90028

country

string

Defines the country.

USA

Example JSON Requests

Simple example (minimum requirements)

{

"email": "[email protected]",

"orderID": "33451",

"purchaseDate": "2018-01-09T22:47:12+0000",

"items": [{

"productID":"1234abcd",

"sku": "ssd-2344-15",

"category": "Shirts",

"name": "Red Flannel"

}]

}

Kitchen sink example (optional fields included)

{

"orderID": "33451",

"email": "[email protected]",

"linkID": "55373eed6c87669bw",

"mcID": "45:55373eed6c87669bwewewee7:ot:55375ba27ec3343a77ce07ec:1422343949",

"customerID": "5432225",

"purchaseDate": "2018-01-09T22:47:12+0000",

"shippingAddress": {

"name": "Mark Smith",

"address": "13130 Silverlake Road",

"city": "Hollywood",

"state": "CA",

"postalCode": 92332,

"country": "USA"

},

"billingAddress": {

"name": " Mark Smith ",

"address": "13130 Silverlake Road",

"city": "Hollywood",

"state": "CA",

"postalCode": 92332,

"country": "USA"

},

"items": [{

"productID":"1234abcd",

"sku": "ssd-2344-15",

"description":"This shirt is amazing!",

"category": "Shirts",

"name": "Awesome Flannel",

"qty": 1,

"url":"http://awesomeflannels.com/1234abcd",

"itemPrice": 129.95,

"images": [

"http://awesomeflannels.com/image_1.jpg", "http://awesomeflannels.com/image_2.jpg"

],

"tags": [

"flannels", "winter"

],

"properties": {

"brands":["Marmot", "Quicksilver"],

"return_date": "2018-07-09T22:47:12+0000"

},

"attr": {

"color": "red",

"size": "large"

}

}],

"tax": 7.00,

"shippingAndHandling": 0.0

}

Adding Order and Item Properties

The properties key can be used to insert additional custom order and item values. Values added using the properties key will become available for segmenting audiences using the Audience Builder (searching of nested order properties must be enabled in your account first). If having searchable order properties is a requirement for your account, please use the properties key in place of the attr key.

Example of adding order properties:

{

"orderID":"33451",

"items": [{

"productID": "1234abcd",

"name": "Red Flannel",

"category": "shirts",

"sku": "ssd-2344-15",

"tags": ["flannels", "winter"]

}],

"properties": {

"color": "red",

"size": "large"

}

})

Example of adding order item properties:

{

"orderID":"33451",

"items": [{

"productID": "1234abcd",

"name": "Red Flannel",

"category": "shirts",

"sku": "ssd-2344-15",

"tags": ["flannels", "winter"],

"properties": {

"brands": ["Marmot", "Quicksilver"]

}

}]

})

Note:

The orderID field must be a unique value.

The cID or primary key field is required. This is the unique identifier for the contact. Cordial does not accept anonymous order records. The default primary key for all accounts is "email".

mcID or linkID are required if you need to attribute the order to a specific message or link within a message. These can be passed in the link as linkID={$linkID}&mcID={$mcID} and stored in a session variable for use in the API

One or more items can be included in an order.

Example POST /orders Request URIs

The following URI in conjunction with the JSON will perform the POST.

http://<path>/orders

GET /orders

Method

URI Path

GET

/orders

Retrieves all orders from the Cordial database.

Using query string parameters, it is also possible to filter the response by contactId to retrieve all orders for a single contact, and filter the response by purchaseDate to limit the data to orders on that date and time. purchaseDate can be filtered by date range using gte and lte filters. (e.g. purchaseDate[gte]=2016-11-10&purchaseDate[lt]=2016-11-11) Additionally, it is possible to filter the field set returned using a query string for the parameter fields.

When retrieving a large amount of orders in the response, it is also possible to apply the per_page and page query string parameters to limit the count returned and page position.

Parameters

Parameter

Type

Description

Example

fields

string

Sets which data fields will be returned.

?fields=shippingAddress

cID

string

Unique contact ID to identify and reference the contact.

?cID=5ada55ed132f37e60e63c04d

email

string

Unique email address to identify and reference the contact.

[email protected]

purchaseDate

string

Filters the data by date using gte and lte.

?purchaseDate[gte]=2017-01-10

page

number

Page number of results.

?page=3

per_page

number

Number of results per page.

?per_page=10

sort_by

string

Column to sort by.

?sort_by=purchaseDate

sort_dir

string

Direction to sort by, works in conjunction with sort_by.

?sort_by=purchaseDate&sort_dir=desc

Example GET /orders Request URIs

The following URI will retrieve all orders and include all fields.

http://<path>/orders

The following URI will retrieve all orders, but only include the field data for the "shippingAddress".

http://<path>/orders?fields=shippingAddress

The following URI will retrieve all orders, and include the field data for both "totalAmount" and "tax".

http://<path>/orders?fields=totalAmount,tax

The following URI will retrieve all orders with a purchaseDate greater than "2017-11-10".

https://api.cordial.io/v1/orders?purchaseDate[gt]=2017-11-10

The following URI will retrieve all orders where the purchaseDate is between "2017-01-10" and "2017-01-11".

https://api.cordial.io/v1/orders?purchaseDate[gte]=2017-01-10&purchaseDate[lte]=2017-01-11

The following URI will retrieve all orders starting from the third page grouping contacts by 10. For example, page 1 would have included the first 10, page 2 the second group of 10 and so on.

http://<path>/orders?page=3&per_page=10

GET /orders/{id}

Method

URI Path

GET

/orders/{id}

Retrieves a specific order from the Cordial database.

The order is defined by the order's unique orderID value.

For example, /orders/112233 would return the response data for the order with the orderID value of 112233.

Additionally, it is possible to filter the field set returned using a query string for the parameter fields.

Parameters

Parameter

Type

Description

Example

fields

string

Sets which data fields will be returned.

?fields=shippingAddress

Example GET /orders/{id} Request URIs

Return records filtered by ID

The following URI will retrieve an order where the id value is 128.

http://<path>/orders/128

Return records filtered by ID field

The following URI will retrieve an order where the id value is 128, but only include the field data for the shippingAddress.

http://<path>/orders/128?fields=shippingAddress

Return records filtered by ID multiple fields

The following URI will retrieve an order where the id value is 128, and include the field data for both totalAmount and tax.

http://<path>/orders/128?fields=totalAmount,tax

PUT /orders{id}

Method

URI Path

PUT

/orders

Updates an order in the Cordial database using the appropriate JSON body.

Example JSON request

The following will update the purchase date of order 33451.

{

"email": "[email protected]",

"orderID": "33451",

"purchaseDate": "2018-01-10T22:47:12+0000"

}

Example PUT /orders Request URIs

The following URI in conjunction with the JSON will perform the PUT.

http://<path>/orders

Parameters

Same requirements and schema asthe POST method above.

DELETE /orders/{id}

Method

URI Path

DELETE

/orders/{id}

Deletes an order from the Cordial database.

The order id defined by the order's unique orderID value.

For example, /orders/22345 would delete the attribute with the orderID value of 22345.

Example DELETE /orders/{id} Request URIs

The following URI will delete an order where the id value is 128.

http://<path>/orders/128

In This Article

Overview

SMS Settings

Configure Your SMS Program

Customize Your Messages

Opt-In Message

Opt-In Confirmation Message

Help Message

Default Stop Message

Test and Preview Your Setup

Notes on SMS Functionality

Subscribe status

Supported regions and countries

SMS short codes use one-way communication

Overview

The SMS channel allows you to send SMS texts to contacts as batch or automated messages using Cordial's native SMS solution.

Please contact your CSMfor details about enabling the SMS channel for your account. The short code provisioning process may take anywhere from 8-12 weeks to complete due to the mobile carriers' requirements.

Once your short code has been approved and SMS channel enabled for your Cordial account, you will gain access to SMS Settings directly in the Account Settings page.

SMS Settings

To access the SMS channel settings, log in to your Cordial account and open the dropdown menu in the top right corner. Navigate to Account Settingsand select theSMS Channel link from the left navigation menu.

creating messages using the SMS channel

Let's explore the available configuration options in more detail.

Configure Your SMS Program

This is where your general SMS program details can be configured. Much of this information will be populated on your behalf by your CSM during the initial SMS channel setup for your account.

SMS shortcode - Your SMS short code. Must be an approved and active short code.

Program name- Enter the name of your program.

Program keyword(optional) - Enter the keyword that contacts will text to your short code in order to subscribe to your SMS program. If not specified, the default opt-in keywords will still apply (YES, Y, OPTIN, OPT-IN).

Brand name - Enter your brand name.

Customize Your Messages

In this section, you can customize your opt-in, confirmation, and help messages. All three messages can be edited at the same time.

Note: To ensure regulatory compliance, double-check that your messages are entered exactly as they appear on your carrier approved SMS short code request form.

Opt-in, confirmation and help messages are allowed 160 characters per message. When the character count exceeds 160, the message in question will be processed as two or more separate messages, depending on length. Additionally, the following extended characters will count as two characters instead of one:

|, ^,, {, }, [, ], ~, \

Opt-In Message

Your contacts will receive the opt-in message immediately after texting YES, Y, OPTIN, OPT-IN, or your program keyword to the short code. Note that a contact will not be subscribed until they confirm their subscription, or double opt-in, by texting back any one of the approved opt-in text codes after receiving the opt-in message. Be sure to include codes for opt-in, help and stop.

Opt-In Confirmation Message

The opt-in confirmation message will be sent to those contacts who confirm their subscription following receipt of the opt-in message.

Following SMS messaging best practices, your confirmation messages should include the following information:

Program name and purpose - Provide the name of your program along with a brief purpose.

Number and frequency of messages - Inform your contacts of message quantity and send frequency they should expect (number of messages/frequency).

Message data & rates disclosure- This is the required verbiage reminding your contacts that their mobile carrier may impose data and messaging fees.

Opt-out instructions - Include valid opt-out codes such as STOP, QUIT, and OPTOUT. Learn more about SMS subscribe status and default codes.

Help and stop codes - Let your contacts know which codes to text for support and to cancel further messages, such as the HELP and STOP codes.

Help Message

The last step is to customize the message that contacts will receive when they respond with the HELP code.

Your help message should include one or more assistance outlets such as a support email address or a customer service phone number. The help message should not result in a dead-end without any recourse.

Tip:Append opt-out and help codes to your messages at least once monthly as a way to remind your contacts how to unsubscribe and where to go for help. Including this reminder will count toward the SMS message 160 character limit so it is best suited for one of your shorter messages.

Default Stop Message

Your contacts can unsubscribe from receiving further SMS messages at any time using any of the approved opt-out codes such as STOP. Contacts will be unsubscribed immediately upon texting an opt-out code and will receive the following notice:

Brand Name: You are unsubscribed from Brand Name alerts. No more messages will

be sent. Reply HELP for help.

Test and Preview Your Setup

You can live preview your opt-in, confirmation, and help messages individually by sending tests to a mobile phone number. Open the Send Test modal and choose which message to test, enter the recipient's phone number, and click Send Test Now.

When you are satisfied with your SMS channel settings, you can begin.

Notes on SMS Functionality

Subscribe status

Subscribing a contact

A contact's SMS channel will be set to subscribed when they send a message to your short code with any of the following text codes (not case sensitive):

y

yes

optin

opt-in

Unsubscribing a contact

Acontact's SMS channel will be set to unsubscribed when they send a message to your short code with any of the following text codes (not case sensitive):

stop

cancel

quit

end

unsubscribe

optout

opt-out

The custom code you created in the Confirmation Message setup.

Note: When a contact texts one of the above unsubscribe messages to your short code, they will be added to a suppression list at the carrier (i.e. Verizon, At&T, etc.) for 90 days. To remove the contact from the carrier's suppression list, they must text UNSTOP to your short code. Note that this will only remove them from the carrier's suppression list, and not change their subscribe status in Cordial. To change their subscribe status, the contact must opt in again by sending one of the opt-in codes.

Supported regions and countries

Currently, only U.S. issued short codes are supported. Your U.S. based short code cannot be used to send messages to non-U.S. phone numbers and over non-U.S. carrier networks.

SMS short codes use one-way communication

SMS short code messages are used for one-way communication and cannot be used for conversational purposes. For example, you can send an SMS to promote a shoe sale, but contacts will not be able to respond with questions regarding the sale or request information on a recent order.

The data stored within the contactactivities collection can be referenced and used within any message body.

Our Example

The getEventRecords Method

How to set the eventName

How to set newerThan

How to set properties

How to set the limit

How to sort the data

Rendering the data in a message

Looping through data with {foreach}

Display unique browse events (deduping)

Referencing an index of the array

Our Example

For our example we'll be using hypothetical event data. In order to test in your system you will need to add your own event data via the API. Learn more about event data.

Using the tabs below you can view the HTML and Smarty used in the message, the event data being referenced (in JSON format) and the rendered output that will display when a message is sent or previewed.

HTML & Smarty

Event Data

Rendered Output

{$browseditems=$supplements->getEventRecords("browse")}

<strong>Items You Browsed</strong><br><br>

{foreach $browseditems as $item}

{$item.properties.title|capitalize}<br>

${$item.properties.price} <br>

{$item.properties.description|capitalize} <br>

{$item.properties.url} <br><br>

{/foreach}

[

{

"cID": "58d2fc99ac0c8117814d4e78",

"_id": "59014a9608ab4e356ec0706a",

"properties": {

"title": "khaki shirt"

"url": "http://example.com/shirt",

"price": 9.99,

"description": "a really cool khaki shirt",

},

"action": "browse",

"time": "2017-04-27T01:34:13+0000",

"email": "[email protected]"

},

{

"cID": "58d2fc99ac0c8117814d4e78",

"_id": "59014a9608ab4e356ec0706a",

"properties": {

"title": "khaki pants"

"url": "http://example.com/pants",

"price": 19.99,

"description": "awesome khaki pants",

},

"action": "browse",

"time": "2017-04-27T01:37:13+0000",

"email": "[email protected]"

},

{

"cID": "58d2fc99ac0c8117814d4e78",

"_id": "59014a9608ab4e356ec0706a",

"properties": {

"title": "suede shoes"

"url": "http://example.com/shoes",

"price": 29.99,

"description": "sweet suede shoes",

},

"action": "browse",

"time": "2017-04-27T01:40:13+0000",

"email": "[email protected]"

}

]

Items You Browsed

Khaki Shirt

$9.99

A Really Cool Khaki Shirt

http://example.com/shirts

Khaki Pants

$19.99

Awesome Khaki Pants

http://example.com/shirt

Suede Shoes

$29.99

Sweet Suede Shoes

http://example.com/shirt

Note: During message creation it is useful to use a Smarty utility to view the available event records in JSON format. For example, you can view all of the available "browse" events for a specified contact the following in a message:

{$browseditems=$supplements->getEventRecords("browse")}

{$utils->jsonPrettyPrint($browseditems)}

The getEventRecords Method

In order to access event data within a message, use the getEventRecords method, which is a custom extension of Smarty provided by Cordial.

The getEventRecords method has 5 parameters: event name, newer than, properties, limit and sort. They must be written in this order and separated by commas. Event name is required, all others are optional.

Note: The contact primary identifier key is implied when rendering event records in a message. Only event records associated with the contact will be available for rendering in a message.

getEventRecords($eventName, $newerThan, $properties, $limit, $sort)

Param

Description

Required

Expected

Default

eventName

The name of the event stored in the contactactivities collection.

Required

Valid event/contactactivity name

N/A

newerThan

Filters the event records returned based on the timestamp of the events.

Optional

Date, null

null

properties

Filters the event records returned based on a matching property value(s).

Optional

Array of property key value pairs

[]

limit

Maximum number of records returned.

Optional

Integer, null

25

sort

Sort order of the event records returned.

Optional

Array of sort instructions

[]

How to set the eventName

All event data is stored in the contactactivities collection and includes standard message events (sends, opens, clicks, etc.), custom events associated with website behavior (browse) and external events captured by IoT devices (opened door, triggered alarm, etc).

In order to make event data available to render in a message, you must specify the event, referenced by the "eventName". You can access event names:

Via the UI by navigating to Analytics Event Data Reports

Via the API by using the GET <path>/contactactivities call. View the interactive API documentation.

Here is an example:

{$browseditems=$supplements->getEventRecords("browse")}

Note: Default limit is 25 even if set to null and order is not guaranteed unless the sort parameter is supplied.

In the example above, a variable "browseditems" is assigned to the resulting data set returned from the contactactivities collection with the event name of "browse". The getEvents method will get the data from "browse" for each message that is rendered per contact.

How to set newerThan

Using the "newerThan" parameter, you can filter the results based on a date. Results will return all events after the date specified.

Return records filtered by a set date.

Example:

{$browseditems=$supplements->getEventRecords("browse","2018-08-19T21:36:13+0000")}

Return records newer than 1 day in the past.

Example:

{$browseditems=$supplements->getEventRecords("browse","-1 day"|date_format:"Y-m-d\TH:i:sO")}

Return records newer than the last send of an Automation.

Using the the Smarty utility, lastSendTimestamp, you are able to set a variable for the last send date of an Automation and populate the newerThan parameter.

last send: {$last_sent_date = $utils->lastSendTimestamp('automation_key')}

{$last_sent_date|date_format:"Y-m-d\TH:i:sO"}

{$browseditems=$supplements->getEventRecords("browse",$last_sent_date|date_format:"Y-m-d\TH:i:sO")}

How to set properties

In some cases, you may want to get specific records from the event data collection. You can achieve this by adding property filters.

Return records filtered by a specified value.

["key"=>"value"]

Example:

{$browseditems=$supplements->getEventRecords("browse",null,["category"=>"shirts"])}

Note: Empty parameters need a placeholder. For the newerThan parameter, use "null" or "false".

Return records filtered by multiple specified values.

["key"=>"value", "key2"=>"value2"]

Example:

{$browseditems=$supplements->getEventRecords("browse",null,["category"=>"shoes,"brand"=>"nike"])}

How to set the limit

Use the limit filter to limit the amount of records returned.

{$browseditems=$supplements->getEventRecords("browse",null,[],5)}

Note: Empty parameters need a placeholder. For the properties array use empty brackets "[]" and for the newerThan parameter, use "null" or "false".

How to sort the data

Sort results by timestamp in ascending order.

{$browseditems=$supplements->getEventRecords("browse",null,[],null,['column'=>'ats','direction'=>'ASC'])}

Sort results by timestamp in descending order.

{$browseditems=$supplements->getEventRecords("browse",null,[],null,['column'=>'ats','direction'=>'DESC'])}

Rendering the data in a message

After the data is available with the getEventRecords method, you can render the data in the message.

Looping through data with {foreach}

A {foreach} statement is the most common way to loop through the data array and render the results in a message.

Example:

{$browseditems=$supplements->getEventRecords("browse")}

{foreach $browseditems as $item}

{$item.properties.title|capitalize}<br>

${$item.properties.price} <br>

{$item.properties.description|capitalize} <br>

{$item.properties.url} <br><br>

{/foreach}

Learn more about using the {foreach} statement.

Display unique browse events (deduping)

A site visitor may view the same item on a website multiple times which will generate duplicate browse events. We can use Smarty to display only the unique events using the following code:

{$browseditems=$supplements->getEventRecords("browse")}

{foreach $browseditems as $item}

{$unique_products[$item.properties.productID] = [

'productID' => $item.properties.productID,

'title' => $item.properties.title,

'price' => $item.properties.price,

'description' => $item.properties.description,

'url' => $item.properties.url

]}

{/foreach}

{foreach $unique_products as $unique_product}

Title: {$unique_product.title}<br>

Price: {$unique_product.price}<br>

Description: {$unique_product.description}<br>

URL: {$unique_product.url}<br><br>

{/foreach}

Referencing an index of the array

You also have to option to target the "nth" item within an array using it's index. For example, if you only wanted to render the first item of the browse array you would write:

{$browseditems=$supplements->getEventRecords("browse")}

{$browseditems[0].properties.title}<br>

${$browseditems[0].properties.price} <br>

{$browseditems[0].properties.category} <br>

{$browseditems[0].url} <br><br>

This example will look in the 1st item of the browse array and render the desired values.

Note: The 1st item of an array is referenced by "0", the second is "1", the third is "2", etc.

In the next article learn about getting JSON feeds.