# How can we help?

## Overview

The includes collection contains information about message content includes stored in the [HTML content library](https://support.cordial.com/hc/en-us/articles/115005531308). 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](https://support.cordial.com/hc/en-us/articles/115005692767-Reusable-HTML-Content-Overview).
- 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](https://support.cordial.com/hc/en-us/articles/216197618).

## 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](https://support.cordial.com/hc/en-us/articles/115005365087) and use it for authorization.

## Methods, parameters, and examples

- [GET/v2/includes](https://support.cordial.com/hc/en-us/articles/360045047572-Message-content-includes-API#getIncludes)
- [GET/v2/includes/{key}](https://support.cordial.com/hc/en-us/articles/360045047572-Message-content-includes-API#getIncludesKey)
- [POST/v2/includes](https://support.cordial.com/hc/en-us/articles/360045047572-Message-content-includes-API#postIncludes)
- [PUT/v2/includes/{key}](https://support.cordial.com/hc/en-us/articles/360045047572-Message-content-includes-API#putIncludesKey)
- [DELETE/v2/includes/{key}](https://support.cordial.com/hc/en-us/articles/360045047572-Message-content-includes-API#delIncludesKey)

## GET/v2/includes

| Method | URL Path |
| --- | --- |
| GET | /v2/includes |
| - Retrieves all message content includes in the HTML content library. <br>- 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.<br>- The include is defined by the include's unique "key" value.<br>- 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.<br>- 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".

```
{
  "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.<br>- The include is defined by the include's unique "key" value.<br>- 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](https://support.cordial.com/hc/en-us/articles/4402427843597-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.