Message content includes API – Cordial Knowledge Base

How can we help?

Overview

The includes collection contains information about message content includes stored in the HTML content library. HTML content can be used for repeated message elements such as headers and footers or to store large experiment code and advanced Smarty functions.

API set name: includes

Additional information

Message content includes are referenced and displayed in a message using Smarty.
Message content includes are compiled and rendered in a message at send time or in message preview.
Content keys must be unique and cannot contain spaces or special characters.
The use of proper HTML markup is highly recommended to avoid message rendering issues. Using HTML block elements within inline elements could distort rendered content.
Depending on your REST API client, you may be required to define the content-type header as application/json. This is not necessary when using the Swagger platform.

Authentication

Cordial's core APIs use HTTP Basic Authentication (BA). From within the Cordial platform, you can generate an encoded API key for your account and use it for authorization.

Methods, parameters, and examples

GET/v2/includes

Method	URL Path
GET	/v2/includes
- Retrieves all message content includes in the HTML content library. - Using query string parameters, it's possible to filter the response by content "key" to retrieve information for a single content include, as well as retrieve only the specified content include fields including: `name`, `createdAt`, `lastUpdate`, and `content`.

The following URL will retrieve all message content includes stored in the HTML content library.

https://<path>/v2/includes

The following URL will retrieve createdAt and name fields of all message content includes stored in the HTML content library.

https://<path>/v2/includes?fields=createdAt,name

GET/v2/includes/{key}

Method	URL Path
GET	/v2/includes/{key}
- Retrieves a single message content include from the HTML content library. - The include is defined by the include's unique "key" value. - For example, /includes/footer would return data for the content include with the key value of "footer".

The following URL will retrieve the message content include with the key of "header".

https://<path>/v2/includes/header

POST/v2/includes

Method	URL Path
POST	/v2/includes
- Adds new message content include to the HTML library using the appropriate JSON body. - Posting more than one time for the same include key will generate an error.

* Required

Parameter	Type	Description	Example
* key	string	Unique message content key to identify and reference the include.	footer
name	string	Message content include name.	Message footer
description	string	A short description for the message content include.	Default message footer
* content	string	HTML or Smarty content to be used as an include in message content.	Hello, world!

The following will create a simple message content include footer within the HTML Content library.

{
  "key": "footer",
  "name": "Message Footer",
  "description": "Default message footer",
  "content": "<table><tr><td>© 2020 Example Company</td></tr></table>"
}

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

https://<path>/v2/includes

PUT/v2/includes/{key}

Method	URL Path
PUT	/v2/includes/{key}
Updates message content include `name`, `description`, and `content` fields.

The following will update the name, description, and content fields of an existing message content include with the key name of "footer".

{
  "name": "Copyright message footer",
  "description": "Default copyright message footer",
  "content": "<table><tr><td>© 2021 Example Company</td></tr></table>"
}

The following URL in conjunction with the JSON will perform the PUT.

https://<path>/includes/footer

DELETE/v2/includes/{key}

Method	URL Path
DELETE	/includes/{key}
- Deletes a message content include from the HTML Content library. - The include is defined by the include's unique "key" value. - For example, /includes/footer would delete the content include with the key value of "footer".

The following URL will delete the message content include with the key value is footer.

https://<path>/v2/includes/footer

Error responses

The Cordial API will return an error object with an errorKey and message if there is a problem with an API call. Below is a list of errors specific to the Message content includes API endpoint, along with suggested modifications to resolve each error. If you receive an error from this API endpoint that is not listed in this table, it's likely recorded within the Global API error responses page.

errorKey	Message	Modifications
INCLUDES_REMOVE_IMPOSSIBLE	Include can't be deleted because it used in next message automation(s) - :automation	The content include you are attempting to remove is being actively used.
INCLUDES_REMOVE_IMPOSSIBLE_BATCHES	Include can't be deleted because it used in next message(s) - :batches	The content include you are attempting to remove is being actively used.
INCLUDES_KEY_UNIQUE	Key must be unique	The content include key must be unique.
CONTENT_VALIDATION_CHARSET	Incorrect charset in message On Line :line, update charset to: charset=UTF-8	Content include contains invalid character encoding. Please set to UTF-8.
CONTENT_VALIDATION_CHARSET_1	Incorrect charset in message Update charset to: charset=UTF-8	Content include contains invalid character encoding. Please set to UTF-8.
CONTENT_VALIDATION_JS	Content may not contain js	Content include may not contain JavaScript.
CONTENT_VALIDATION_BLOCKS	Block tag detected in content. Please use the Sculpt Editor.	The Sculpt Editor will provide a live preview for testing.