How can we help?

Search

Message content includes API

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. <h2>Hello, world!</h2>

  • 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". Note that message content include key can not be updated once set.

    {
  "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

Test in Swagger

You can access and test Cordial's APIs in Swagger.

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.

Comments

0 comments

Please sign in to leave a comment.