Manage Images in Marketing Cloud Next

To add an image to your Marketing Cloud Next content workspace, upload a file from your computer, reuse a file from your content workspace, or specify an image URL. You can include images in emails, landing pages, forms, and content blocks.

Prerequisite 

Retrieve the ID of the folder or workspace where you want to add the image. See Manage Content Workspaces and Manage Content Folders.

Add an Image to Your Content Workspace 

Add an image to your content workspace by using one of these methods.

  • Upload an image file from your computer.
  • Create an image from a file in your content workspace.
  • Reference an image hosted at an external URL.

For all three methods, issue a POST request to the /services/data/{apiVersion}/connect/cms/contents endpoint. In the request body, include the properties in this table.

PropertyData TypeDescription
contentBody.altTextstringAlternative text that describes the image.
contentBody.sfdc_cms:media.source.refstringRequired only when you use a file that exists in your content workspace. The CMS file ID of the file. Omit this property when you upload a file.
contentBody.sfdc_cms:media.source.typestringRequired. The source of the image. Use file for an uploaded file or a file in your content workspace. Use url for an externally hosted image.
contentBody.sfdc_cms:media.source.urlstringRequired only when you reference an external URL. The public URL of the image.
contentBody.thumbnailobjectThe thumbnail image.
contentSpaceOrFolderIdstringRequired. The ID of the workspace or folder to add the image to.
contentTypestringRequired. The type of the content item. For images, use sfdc_cms__image.
titlestringRequired. A name that identifies the image in your content workspace. Specify the title at the top level of the request body, not inside contentBody.

The contentBody object accepts only altText, thumbnail, and sfdc_cms:media. If you include any other property, such as sfdc_cms:title or sfdc_cms:description, the API returns an HTTP 400 response.

Important

The API determines the correct size and mimeType properties for the image, so don’t include them in your request.

You can add an GIF, JPG, JPEG, PNG, SVG, or WEBP file up to 25 MB.

Add an Image by Uploading a File 

To upload an image file, issue a multipart/form-data POST request. The request includes two parts:

  • A JSON part named ManagedContentInputParam with the content type application/json. This part contains the image metadata.
  • A binary part named contentData. Set its content type to match the type of image, such as image/jpeg. This part contains the image file data.

In the ManagedContentInputParam part, set contentBody.sfdc_cms:media.source.type to file. Don’t include ref, size, or mimeType.

Request Example
1POST /services/data/{apiVersion}/connect/cms/contents HTTP/1.1
2Host: {subdomain}.my.salesforce.com
3Content-Type: multipart/form-data; boundary=BOUNDARY
4Authorization: Bearer YOUR_BEARER_TOKEN
5
6--BOUNDARY
7Content-Disposition: form-data; name="ManagedContentInputParam"
8Content-Type: application/json; charset=UTF-8
9
10{
11  "contentSpaceOrFolderId": "0Zuxx00000003M5CAI",
12  "contentType": "sfdc_cms__image",
13  "title": "Product Hero Image",
14  "contentBody": {
15    "altText": "Product lifestyle shot",
16    "sfdc_cms:media": {
17      "source": {
18        "type": "file"
19      }
20    }
21  }
22}
23--BOUNDARY
24Content-Disposition: form-data; name="contentData"; filename="product-hero.jpg"
25Content-Type: image/jpeg
26
27<binary image data>
28--BOUNDARY--

Name the file part contentData. If you use a different name, the API returns an HTTP 400 response with the error POST_BODY_PARSE_ERROR.

Note

The API returns 201 Created, and the response body includes metadata about the image. The response contains the uploaded file’s CMS file ID in contentBody.sfdc_cms:media.source.ref and a CMS delivery path in contentBody.sfdc_cms:media.url.

Response Example
1{
2  "managedContentId": "20Yxx0000009OQtp2AG",
3  "managedContentVariantId": "9Psxx000008pelB0AQ",
4  "managedContentVersionId": "5OUxx00000909an4AA",
5  "contentKey": "MCUGHUGC7LSRFAHHE234PWYFIAQI",
6  "title": "Product Hero Image",
7  "contentType": {
8    "fullyQualifiedName": "sfdc_cms__image"
9  },
10  "contentBody": {
11    "altText": "Product lifestyle shot",
12    "sfdc_cms:media": {
13      "source": {
14        "type": "file",
15        "ref": "0sNxx00000GiIHl",
16        "size": 245760,
17        "mimeType": "image/jpeg"
18      },
19      "url": "/cms/media/MCUGHUGC7LSRFAHHE234PWYFIAQI?version=1.1"
20    }
21  },
22  "isPublished": false,
23  "status": {
24    "label": "Draft",
25    "status": "Draft"
26  }
27}

Add an Image by Using an Uploaded CMS File 

To create an image from a file in your content workspace, issue a POST request with the content type application/json. Set contentBody.sfdc_cms:media.source.type to file, and set contentBody.sfdc_cms:media.source.ref to the ref value from the response of an earlier upload.

Request Example
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": "0Zuxx00000003M5CAI",
8  "contentType": "sfdc_cms__image",
9  "title": "Product Hero Image (copy)",
10  "contentBody": {
11    "altText": "Product lifestyle shot",
12    "sfdc_cms:media": {
13      "source": {
14        "type": "file",
15        "ref": "0sNxx00000GiIHl"
16      }
17    }
18  }
19}

The API returns 201 Created.

The ref property accepts only a CMS file ID. If you specify a content document or content version ID, the API returns an HTTP 400 response with the error INVALID_FIELD and the message “This image reference isn’t available.”

Note

Add an Image by Specifying an External URL 

To reference an image hosted at an external URL, issue a POST request with the content type application/json. Set contentBody.sfdc_cms:media.source.type to url, and set contentBody.sfdc_cms:media.source.url to the public URL of the image.

Request Example
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": "0Zuxx00000003M5CAI",
8  "contentType": "sfdc_cms__image",
9  "title": "Product Hero Image",
10  "contentBody": {
11    "altText": "Product lifestyle shot",
12    "sfdc_cms:media": {
13      "source": {
14        "type": "url",
15        "url": "https://example.com/images/product-hero.jpg"
16      }
17    }
18  }
19}

The API returns 201 Created.

Publish an Image 

New images start as drafts. To make an image available to use in messages, publish it by using the managedContentId value from the response. For more information, see Publish Content Items.

See Also