Automation Templates

• 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

Parameters

*Required

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": "info@example.com",
			"replyEmail": "info@example.com",
			"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

Query String Parameters

?fields=key%2ClastUpdate

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

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

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

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

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

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

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

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

?tags=welcome%2C%20promo

?page=3

?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}

Query String Parameters

?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}

Parameters

*Required

Example JSON Requests

The following will update the subject for an automation template.

{
	"message": {
		"headers": {
			"subject": "Big Sale This Weekend",
			"fromEmail": "info@example.com",
			"replyEmail": "info@example.com",
			"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

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

Parameters

*Required

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

Example JSON Requests

The following will send to a single email address.

{
    "to": {
        "contact": {
            "email": "msmith@example.com"
        },
        "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

Parameters

*Required

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

Example JSON Requests

The following will send to a single email address.

{
    "to": {
        "contact": {
            "email": "msmith@example.com"
        },
        "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.

{
    "to": 
    [
        {
            "contact": {
                "email": "msmith@example.com"
            },
            "extVars": {
                "orderID": "123",
                "orderItems": [
                    {
                        "name": "Tour Tee",
                        "amount": "22.50"
                    },
                    {
                        "name": "Icon Tee",
                        "amount": "25.50"
                    },
                    {
                        "name": "Icon Hat",
                        "amount": "15.50"
                    }
                ]
            }
        },
        {
            "contact": {
                "email": "jsmith@example.com"
            },
            "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 their subscriber status to subscribed. Note the channels addition to the JSON.

{
    "to": {
        "contact": {
            "channels": {
                "email": {
                    "address": "msmith@example.com",
                    "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

DELETE /automationtemplates/{key}

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}

Query String Parameters

?experiment=SubjectTest&variant=Left_Cart_Items

?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}

Query String Parameters

?experiment=SubjectTest&variant=Left_Cart_Items

?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