Create and Manage Email Templates in Marketing Cloud Next

Use the CMS Contents endpoints in Connect API to create and manage email templates in your marketing content workspace.

Prerequisite

Retrieve the ID of the workspace to create the email template in. See Manage Content Workspaces.

Create an Email Template with HTML

To create an email template using raw HTML content, issue a POST request to the /services/data/{apiVersion}/connect/cms/contents endpoint.

This table lists the properties in the request body.

Property	Data Type	Description
`contentSpaceOrFolderId`	string	Required. The ID of the workspace to create the email template in.
`contentType`	string	Required. The type of content. To create an email template, specify `sfdc_cms__emailTemplate`.
`contentBody.sfdc_cms:title`	string	Required. An identifying name for the email template.
`contentBody.subjectLine`	string	Required. The default subject line for the email template.
`contentBody.preheader`	string	Preview text that’s shown after the subject line in some email clients.
`contentBody.messagePurpose`	string	The purpose of the email. Possible values are `promotional` or `transactional`.
`contentBody.rawHtml`	string	Required. The HTML content of the email template.

This sample request shows how to create a basic HTML email template.

1POST /services/data/{apiVersion}/connect/cms/contents HTTP/1.1
2Host: {subdomain}.my.salesforce.com
3Content-Type: application/json
4Authorization: Bearer YOUR_BEARER_TOKEN
5
6{
7  "contentSpaceOrFolderId": "0ZuQZ0000004YSv0AM",
8  "contentType": "sfdc_cms__emailTemplate",
9  "contentBody": {
10    "messagePurpose": "promotional",
11    "preheader": "Updates, resources, and more — take a look at what’s ready.",
12    "rawHtml": "<html><head><title>Sample HTML Email</title></head><body><h1>Welcome Back</h1><p>We have updates, resources, and new content ready for you. Explore what’s new and make the most of everything available to you.</p>",
13    "sfdc_cms:title": "Sample HTML Email Template",
14    "subjectLine": "What’s New"
15  }
16}

If the request is successful, the response includes metadata about the email template.

1{
2  "contentKey": "MCNUSLTYAES5CLRKYWXFUXDXW2BM",
3  "contentSpace": {
4    "id": "0ZuQZ0000004YSv0AM",
5    "resourceUrl": "/services/data/v67.0/connect/cms/spaces/0ZuQZ0000004YSv0AM"
6  },
7  "contentType": {
8    "fullyQualifiedName": "sfdc_cms__emailTemplate"
9  },
10  "isPublished": false,
11  "managedContentId": "20YQZ0000007G3F2AU",
12  "managedContentVariantId": "9PsQZ00000072oH0AQ",
13  "status": {
14    "label": "Draft",
15    "status": "Draft"
16  },
17  "title": "Sample HTML Email Template",
18  "versionNumber": "1.0"
19}

The email template is created in Draft status. To make it available for use in messages, copy the value of the managedContentId property, and then publish the email template.

Create an Email Template with Components

To create an email template that uses components, issue a POST request to the /services/data/{apiVersion}/connect/cms/contents endpoint with an sfdc_cms:block structure.

This table lists the properties in the request body.

Property	Data Type	Description
`contentSpaceOrFolderId`	string	Required. The ID of the workspace to create the email template in.
`contentType`	string	Required. The type of content. To create an email template, specify `sfdc_cms__emailTemplate`.
`contentBody.sfdc_cms:title`	string	Required. An identifying name for the email template.
`contentBody.subjectLine`	string	Required. The default subject line for the email template.
`contentBody.sfdc_cms:block`	object	The structure of the component block. Each content node in the block requires a unique ID, such as a UUID.

1POST /services/data/{apiVersion}/connect/cms/contents HTTP/1.1
2Host: {subdomain}.my.salesforce.com
3Content-Type: application/json
4Authorization: Bearer YOUR_BEARER_TOKEN
5
6{
7  "contentSpaceOrFolderId": "0ZuQZ0000004YSv0AM",
8  "contentType": "sfdc_cms__emailTemplate",
9  "contentBody": {
10    "sfdc_cms:title": "Sample Component Email Template",
11    "subjectLine": "Welcome to Our Newsletter",
12    "preheader": "Check out what’s new",
13    "messagePurpose": "promotional",
14    "sfdc_cms:block": {
15      "id": "GENERATE_UUID",
16      "type": "sfdc_cms:documentBlock",
17      "contentNodes": [
18        {
19          "id": "GENERATE_UUID",
20          "type": "sfdc_cms:documentBlock",
21          "contentNodes": [
22            {
23              "id": "GENERATE_UUID",
24              "type": "sfdc_cms:paragraphBlock",
25              "contentNodes": [
26                {
27                  "id": "GENERATE_UUID",
28                  "type": "sfdc_cms:textBlock",
29                  "text": "Welcome to our newsletter!"
30                }
31              ]
32            }
33          ]
34        }
35      ]
36    }
37  }
38}

Retrieve an Email Template

To retrieve details of an email template, issue a GET request to the /services/data/{apiVersion}/connect/cms/contents/{contentKey} endpoint. Replace {contentKey} with the unique ID or the API name of the email template.

1GET /services/data/{apiVersion}/connect/cms/contents/MCNUSLTYAES5CLRKYWXFUXDXW2BM HTTP/1.1
2Host: {subdomain}.my.salesforce.com
3Authorization: Bearer YOUR_BEARER_TOKEN

If the request is successful, the response includes the email template details.

1{
2  "contentKey": "MCNUSLTYAES5CLRKYWXFUXDXW2BM",
3  "managedContentId": "20YQZ0000007G3F2AU",
4  "managedContentVariantId": "9PsQZ00000072oH0AQ",
5  "title": "Sample HTML Email Template",
6  "status": {
7    "status": "Draft"
8  },
9  "contentType": {
10    "fullyQualifiedName": "sfdc_cms__emailTemplate"
11  },
12  "contentBody": {
13    "sfdc_cms:title": "Sample HTML Email Template",
14    "subjectLine": "What’s New",
15    "preheader": "Updates, resources, and more — take a look at what’s ready.",
16    "rawHtml": "<html><head><title>Sample HTML Email</title></head><body><h1>Welcome Back</h1><p>We have updates, resources, and new content ready for you. Explore what’s new and make the most of everything available to you.</p>"
17  },
18  "contentSpace": {
19    "id": "0ZuQZ0000004YSv0AM"
20  }
21}

Update an Email Template

To update an email template, use the retrieve endpoint to find the managedContentVariantId of the email template. Next, issue a PUT request to the /services/data/{apiVersion}/connect/cms/contents/variants/{variantId} endpoint.

You can’t switch between raw HTML email templates and component-based email templates during an update.

Note

This sample request shows how to update the content of an email template.

1PUT /services/data/{apiVersion}/connect/cms/contents/variants/9PsQZ00000072oH0AQ HTTP/1.1
2Host: {subdomain}.my.salesforce.com
3Content-Type: application/json
4Authorization: Bearer YOUR_BEARER_TOKEN
5
6{
7  "contentBody": {
8    "messagePurpose": "promotional",
9    "preheader": "Updated preview text",
10    "rawHtml": "<h1>Updated Content</h1><p>New content here</p>",
11    "sfdc_cms:title": "Updated Template Title",
12    "subjectLine": "Updated Subject"
13  }
14}

Include the full contentBody in PUT requests. If you omit properties from the request body, they’re deleted from the email template.

Note

The email template remains in its current status (Draft or Published) after the update. To change the status, use the publish or unpublish endpoints.

Clone an Email Template

To create a copy of an existing email template, issue a POST request to the /services/data/{apiVersion}/connect/cms/contents/{contentKey}/clone endpoint. Replace {contentKey} with the unique ID or API name of the email template to clone.

1POST /services/data/{apiVersion}/connect/cms/contents/MCNUSLTYAES5CLRKYWXFUXDXW2BM/clone HTTP/1.1
2Host: {subdomain}.my.salesforce.com
3Authorization: Bearer YOUR_BEARER_TOKEN

The cloned email template is created in Draft status and includes all content body fields and structure from the original. To differentiate the clone from the original, update the cloned email template’s title.

Delete an Email Template

To delete an email template, issue a DELETE request to the /services/data/{apiVersion}/connect/cms/contents/variants/{variantId} endpoint. Replace {variantId} with the managedContentVariantId of the email template.

Deleting an email is permanent and can’t be undone.

Important

This sample request shows how to delete an email by providing its variant ID.

1DELETE /services/data/{apiVersion}/connect/cms/contents/variants/9PsQZ00000072oH0AQ HTTP/1.1
2Host: {subdomain}.my.salesforce.com
3Authorization: Bearer YOUR_BEARER_TOKEN

A successful deletion returns a 204 No Content status with no response body.

Publish an Email Template

To publish a draft email template and make it available for use in messages, see Publish Content Items.