Salesforce Docs Portal

Create and Manage Emails in Marketing Cloud Next

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

Prerequisite

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

Create an Email with HTML

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

note: After you create a raw HTML email, you can’t change it to use a component-based 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 in.
contentType string Required. The type of content. To create an email, specify sfdc_cms__email.
contentBody.sfdc_cms:title string Required. An identifying name for the email.
contentBody.subjectLine string Required. The email subject line.
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.

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

POST /services/data/{apiVersion}/connect/cms/contents HTTP/1.1
Host: {subdomain}.my.salesforce.com
Content-Type: application/json
Authorization: Bearer YOUR_BEARER_TOKEN

{
  "contentSpaceOrFolderId": "0ZuQZ0000004YSv0AM",
  "contentType": "sfdc_cms__email",
  "contentBody": {
    "messagePurpose": "promotional",
    "preheader": "Updates, resources, and more — take a look at what's ready.",
    "rawHtml": "<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><a href='https://example.com/welcome'>Get Started</a>",
    "sfdc_cms:title": "Sample HTML Email",
    "subjectLine": "What’s New for You"
  }
}

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

{
  "contentKey": "MCNUSLTYAES5CLRKYWXFUXDXW2BM",
  "contentSpace": {
    "id": "0ZuQZ0000004YSv0AM",
    "resourceUrl": "/services/data/v68.0/connect/cms/spaces/0ZuQZ0000004YSv0AM"
  },
  "contentType": {
    "fullyQualifiedName": "sfdc_cms__email"
  },
  "isPublished": false,
  "managedContentId": "20YQZ0000007G3F2AU",
  "managedContentVariantId": "9PsQZ00000072oH0AQ",
  "status": {
    "label": "Draft",
    "status": "Draft"
  },
  "title": "Sample HTML Email",
  "versionNumber": "1.0"
}

The email 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.

Create an Email with Components

To create an email 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 in.
contentType string Required. The type of content. To create an email, specify sfdc_cms__email.
contentBody.sfdc_cms:title string Required. An identifying name for the email.
contentBody.subjectLine string Required. The email subject line.
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. 
POST /services/data/{apiVersion}/connect/cms/contents HTTP/1.1
Host: {subdomain}.my.salesforce.com
Content-Type: application/json
Authorization: Bearer YOUR_BEARER_TOKEN

{
  "contentSpaceOrFolderId": "0ZuQZ0000004YSv0AM",
  "contentType": "sfdc_cms__email",
  "contentBody": {
    "sfdc_cms:title": "Sample Component Email",
    "subjectLine": "Welcome to Our Newsletter",
    "preheader": "Check out what’s new",
    "messagePurpose": "promotional",
    "sfdc_cms:block": {
      "id": "GENERATE_UUID",
      "type": "sfdc_cms:documentBlock",
      "contentNodes": [
        {
          "id": "GENERATE_UUID",
          "type": "sfdc_cms:documentBlock",
          "contentNodes": [
            {
              "id": "GENERATE_UUID",
              "type": "sfdc_cms:paragraphBlock",
              "contentNodes": [
                {
                  "id": "GENERATE_UUID",
                  "type": "sfdc_cms:textBlock",
                  "text": "Welcome to our newsletter!"
                }
              ]
            }
          ]
        }
      ]
    }
  }
}

Retrieve an Email

To retrieve details of an email, 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.

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

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

{
  "contentKey": "MCNUSLTYAES5CLRKYWXFUXDXW2BM",
  "managedContentId": "20YQZ0000007G3F2AU",
  "managedContentVariantId": "9PsQZ00000072oH0AQ",
  "title": "Sample HTML Email",
  "status": {
    "status": "Draft"
  },
  "contentType": {
    "fullyQualifiedName": "sfdc_cms__email"
  },
  "contentBody": {
    "sfdc_cms:title": "Sample HTML Email",
    "subjectLine": "What’s New for You",
    "preheader": "Updates, resources, and more — take a look at what’s ready.",
    "rawHtml": "<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><a href='https://ex.com/welcome'>Get Started</a>",
  },
  "contentSpace": {
    "id": "0ZuQZ0000004YSv0AM"
  }
}

Update an Email

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

PUT /services/data/{apiVersion}/connect/cms/contents/variants/9PsQZ00000072oH0AQ HTTP/1.1
Host: {subdomain}.my.salesforce.com
Content-Type: application/json
Authorization: Bearer YOUR_BEARER_TOKEN

{
  "contentBody": {
    "messagePurpose": "promotional",
    "preheader": "Updated preview text",
    "rawHtml": "<h1>Updated Content</h1><p>New content here</p>",
    "sfdc_cms:title": "Updated Email Title",
    "subjectLine": "Updated Subject"
  }
}

important: Provide the full contentBody. Fields that aren’t included in the request are cleared. You can’t switch between HTML and component structures during an update.

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

Clone an Email

To create a copy of an email, use the retrieve endpoint to find the contentKey of the email. Next, issue a POST request to the /services/data/{apiVersion}/connect/cms/contents/{contentKey}/clone endpoint.

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

The cloned email is created in Draft status and includes the same content body fields and structure as the original version.

Delete an Email

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

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

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

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

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

Publish an Email

Before you can use an email in messages, you must publish it.

See Also