Explore the Salesforce Marketing Cloud APIs with a Postman Collection

Salesforce Marketing Cloud exposes a rich set of APIs that allow you to integrate your Marketing Cloud instance with third party systems in a variety of scenarios. There is robust documentation on the available APIs, but we wanted to provide a quick and easy way to get started using those APIs as well as understand the details and see example calls.

In this post, I’ll introduce you to Postman and show you how to easily explore and test different Marketing Cloud APIs against multiple instances using an open source Postman collection. This unofficial collection currently holds over 140 API call templates for both the REST and SOAP Marketing Cloud APIs.

About Postman
Postman is a desktop application that lets you configure and call HTTP-based APIs like REST or SOAP. It’s a very convenient and powerful tool that leverages point and click configuration. It supports environment variables, team workspaces and JavaScript automation among other useful features.

Introducing the Salesforce Marketing Cloud API Collection

A bit of history

Historically, an internal group of solution engineers and architects created and maintained a static collection of common calls and stored that collection in GitHub. This is the collection that many of you have stored and are using today.

Since this initial collection was launched, two important things happened that changed the foundation of the collection. In October 2018, Marketing Cloud introduced tenant-specific subdomains in order to enhance the performance of the Marketing Cloud platform. Additionally, in November 2020, Postman announced the launch of Public Workspaces which allowed us to provide a baseline collection and leverage community contributions to continue to build and enhance the collection.

Collection overview

Today, the Marketing Cloud collection can be found on the Postman Salesforce Developers team page, and setup and use instructions can be found on GitHub. The collection includes 140+ request templates grouped by product category, architecture/protocol, and finally, product capability.

Product category – currently the collection supports the Messaging and Journeys portions of Marketing Cloud. Further enhancements to add other product categories will be coming out in the future.
Architecture/Protocol – given that Marketing Cloud supports multiple approaches to API integration, we have categorized the capabilities to align with REST architecture and SOAP protocol. Given that the patterns for SOAP integration are similar, the collection provides examples for all methods but not all objects, currently. This is a great opportunity for community collaboration to continue to build this portion of the collection.
Product capability – at this level, we’re seeing the individual requests grouped by capability within the product. For example, requests relevant to creating new Content Builder assets, sending transactional messages, or interacting with data extensions to name a few.

Building from API request templates instead of going into each API’s documentation can save you a lot of time and greatly reduce the risk of errors. However, the Salesforce Marketing Cloud APIs Collection doesn’t replace the documentation. You’ll need to use Postman in combination with the API’s documentation.

Variables and authorization

The collection leverages variables for maximum flexibility. This allows us to dynamically construct requests based on the configuration supplied by the end user. There are four key variables defined at the collection level that you will need to setup in order to use the collection.

et_subdomain
et_clientId
et_clientSecret
et_mid

Detailed instructions on how to set them up can be found in the collection installation instructions.

We wanted to make the use of this collection as easy as possible. Part of that includes automating the authorization with a pre-request script at the collection level. If you’re interested in the details of how the pre-request script works you can find more information here.

So what does this mean for you as a user of the collection? It means you don’t have to manually issue the authorization call or copy and paste that authorization token in all future requests. Pretty cool, right?

Multiple instances/environments

You may be working with multiple Marketing Cloud instances that support dev/test/prod scenarios. Manually changing collection variables each time you switch instances would be a pain… but thanks to Postman Environments, you can save precious time. Refer to the environment setup documentation for more information.

Sample use case: creating an asset

Before jumping into the example, make sure to complete the following pre-work:

Install Postman.
Import the Salesforce Marketing Cloud APIs Collection and follow the project readme for instructions.

For the purpose of this example, you’ll be a developer at Makana Health, a fictitious healthcare organization. You’ve been tasked with integrating a content management system (CMS) with Marketing Cloud via API. The goal is to have assets automatically published to Marketing Cloud without users having to manually upload the asset.

In this scenario, the CMS will make a request to import an asset into Marketing Cloud once the asset has been approved. Before you can start to develop the process of building this integration, you’ll want to do some testing with the API to understand how the request needs to be structured, what the response body looks like, and how the asset resides in Marketing Cloud.

As always, a good start is to head for the API documentation in order to learn about the request’s usage and the required fields.

Now that you know more about the API request, let’s create it in Postman:

Select Messaging & Journeys → REST → Assets (Content Builder) → Content → Create Asset – Image request.
Provide a name for the asset in the name property. This will be the display name of the asset in Content Builder.
We’ll upload a PNG asset type so we can leave the assetType details as they are. If you upload a different asset type you can make changes based on the Asset Type documentation.
Provide a name for the file in the FileProperties.fileName property. This will be the name of the asset stored in Marketing Cloud.
Find a PNG image you’d like to upload. Use a service like this to convert it to Base64 and paste the resulting string as the value for the file property.

Hit the Send button and you’re done! You should see a Status of 201 – Created and you will now see your new asset in Content Builder for use in various Marketing Cloud messages and landing pages.

You can now:

Replay the request at will in your dev or testing environment and help troubleshoot potential issues
Generate and share the code to make this call in several programming languages
Use your findings to help design the integration between your CMS and Marketing Cloud

Summary

Now that you know about Postman and this great API collection, follow the getting started instructions and explore the Marketing Cloud APIs. Can’t find the API request you need in the collection? Feel free to contribute to the repository, it’s open source!

On the roadmap for the collection we intend to expand the SOAP collection for Messaging & Journeys as well as add Interaction Studio and Pardot categories and supporting requests.

About the author

Aaron Cates is a Principal Marketing Cloud Architect at Salesforce based in central Arkansas. He supports the Healthcare and Life Sciences operating unit in the Marketing Cloud helping customers enhance their member and patient experiences. He is currently 9x Salesforce certified and enjoys continuously learning about new technologies both inside and outside Salesforce.