How to Test API Requests in Mailchimp

Email marketing uses API requests to transfer the data from the site to the email platform. It can be the subscribers to the list transfer, adding tags to them, changing the meanings of the additional fields, sending trigger emails from the platform on request.

In complex email marketing platforms everything is built upon such requests. But even the small projects sometimes lack the basic integrations that the platform offers, so you need to create the custom API requests.

This article will be useful for email marketers, will help them to understand how to create an API request in Mailchimp and to send it to the setting for the backend developer. The request is set up in PHP on a website and we will provide you with such examples, but we will pay more attention to the requests a marketer will use.

In this article we will examine the ways of working with API requests in Mailchimp. In theory, an email marketer should read the API guide by Mailchimp and on the basis of this information he or she should create the requests and specifications for the requests. But in practice it can take much effort and time.

We will examine the examples of the API requests that can be tested. You can take the examples of these requests, change the data in them according to your project and test.

Getting ready for testing

First of all, we need to download Postman — a program for testing the requests. We will create our request and send it to the platform in it. Doing this we can check if our request is correct and if all the data goes to the platform.

Next we will create a request URL and body and will test their work in the Postman. And for some of them we will add an example of a request for PHP that a developer may need.

This is what the program’s interface looks like.

Request URL

Here we write the request URL and method. There are two the most common request methods:

1. POST if you need to transfer data;
2. GET if you need to acquire data. For example, if we collect the email channel report in Power BI, then we’ll use the get requests.

We will show the examples of what we type in the URL field later.

Authorization tab

To access the platform while doing some requests you will need to authorize. Whether this process is obligatory depends on the platform you’re working with and with its API.

For example, while testing the requests in ExpertSender you don’t need to authorize as all the data needed is already in the request. if we are working with the API by toggl then we need to authorize with the login and password for the account. And for Mailchimp we’ll need to use Basic Auth that uses API key as a password. So you enter your email or login in the Username tab and your API key in the Password tab.

But, you may have several sub accounts and want to test the requests from a different account that is connected to your account. In this case you need to change the password only, your login remains the same.

You can find your API key in the Account->Extras->API keys tab.

The API key as it is is an important part of any request and should be used either in the request body or while authorizing.

Request body

It is the main part of the request. In it we write what we want to do. For example, if we add a subscriber into the list, we write his or her email, the meaning of the additional fields and assign various parameters. Generally json and xml requests are used. It is important to place the syntax correctly in the request body: close the brackets where needed or place a comma. These things are easy to miss if you have no experience in creating the requests, but without them the request will be incorrect.

Response

Here Postman will show the answer to the request. If the request doesn’t for some reason, the detailed description of the error should be here. As an answer to a successful request the 201 created status appears and it also depends on the platform’s API.

The subscribers operations request: adding, deleting, changing

This operation is used while transfering a subscriber to the platform from the subscription or registration form.

Request URL

https://<dc>.api.mailchimp.com/3.0/lists/{list_id}/members/

The main parameters:

• {list_id} is a unique audience id that you add a subscriber into. You can find it in the audience settings.

• dc is your server in Mailchimp. It can be found in the address bar here:

In my example it is us17.

Request Body

{
"email_address": "youremail@gmail.com",
"status": "subscribed",
"merge_fields": {
"FIRSTNAME": "",
"LASTNAME": ""
}
}

The main parameters:

• email_address — it is the subscriber’s email, so this field is obligatory;
• status — the subscriber’s status when we transfer him or her into the list. In our case we need the “subscribed” status;
• merge_fields — additional fields that we fill in for the user when he or she subscribes.

The status field should be mentioned separately. It may have one of the next meanings:

• subscribed — it allows to subscribe a person to the emails at once;
• pending — it allows to send double opt in when getting to the list;
• unsubscribed — it allows to unsubscribe the user from the emails;
• cleaned — it allows to delete the contact from the list because of invalidity.

Depending on your goal you can use different meanings of this field in your request.

There are only two additional fields used in the example: firstname and lastname. In fact you can transfer any meaning to any field that you have in the platform.

So, if your form has a non-standard field, then you’ll need to first create it in Mailchimp and then write the data transfer in your request. You can create such fields in the “Merge Fields” tab in the audience settings.

This way we create the additional fields of the needed type. We use exactly the MERGE tags meanings, not the Field label and type. The parameter needed is highlighted in the screenshot.

So, you can add as many additional fields to your request as you need. The main thing is not to make a mistake with the punctuation marks in the request. After every field you need to place a comma, but after the last field in the request there should be no punctuation marks. If you make a mistake, the request won’t go and Postman will return your message with an error. It is easy to notice a mistake in the programm — it will be marked with a little cross.

The same icon will be used to highlight all the syntactic mistakes: incorrectly closed quote marks or brackets.

PHP Request

This type of the request will be useful for backend developers when they will be realizing the request script on a website.

require_once('/path/to/MailchimpMarketing/vendor/autoload.php');

$Mailchimp = new \MailchimpMarketing\ApiClient();

$Mailchimp->setConfig([
'apiKey' => 'YOUR_API_KEY',
'server' => 'YOUR_SERVER_PREFIX'
]);

$email = "urist.mcvankab@example.com";
$list_id = "YOUR_LIST_ID";

try {
$response = $client->lists->addListMember($list_id, [
"email_address" => "prudence.mcvankab@example.com",
"status" => "subscribed",
"merge_fields" => [
"FNAME" => "Prudence",
"LNAME" => "McVankab"
]
]);
$response = $Mailchimp->lists->addListMember($list_id, $contact);
// TODO: Get the new member's ID from the response and echo it
//echo "Successfully added contact as an audience member. The contact's id is {$response->getId()}.";
} catch (MailchimpMarketing\ApiException $e) {
echo $e->getMessage();
}

Sending an email by request

Request URL

https://<dc>.api.Mailchimp.com/3.0/automations/<workflow id>/emails/<email id>/queue

Here we add two new variables:

• workflow id
• email id

You can find them with the help of two get requests. If the POST request sends something like commands to the system and says what to do, then the GET request takes the data. The request type near the url changes.

Firstly we search for the workflow id

https://<dc>.api.Mailchimp.com/3.0/automations/

In a response Postman will show all the data on all the automations that there are in the account. The automation needed will have the API 3.0 type. You can also recognize it by the theme of the email.

The id space meaning is what we are looking for. All that’s left to do is to learn the id of the email. To do it we send a request:

https://<dc>.api.Mailchimp.com/3.0/automations/<workflow i>/emails

We get the automation data that will contain the email id. After this we can place the data into the original request and send the email.

Request Body

{
"email_address": "youremail@gmail.com"
}

Here we just transfer the addressee’s email. The user is needed to be in your subscribers list for the letter to be sent correctly. This is why in some cases you need to realize several requests at once, including the add the subscriber into the list ones.

Assigning a tag to a subscriber

Request URL

https:/<dc>.api.Mailchimp.com/3.0/lists/{list_id}/members/<member_id>/tags

<member_id> is the email of the subscriber that you want to assign a tag to, syphered in the md5 hash with the help of md5 Hash Generator. Mailchimp probably syphers the data for security — not to transfer the sunsvriber’s email directly in the request URL. Just input the needed email and you will get a hash that can be put into the request URL.

Request Body

{
"tags": [
{
"name": "product",
"status": "active"
}
]
}

The request body is very simple. There should be “active” status and we write the tag we want to assign to the user in the “name”. All other information, including the user’s email, is transfered into the request URL.

PHP Request

require_once('/path/to/MailchimpMarketing/vendor/autoload.php');

$Mailchimp = new MailchimpMarketing\ApiClient();

$Mailchimp->setConfig([
'apiKey' => 'YOUR_API_KEY',
'server' => 'YOUR_SERVER_PREFIX'
]);

$list_id = "YOUR_LIST_ID";

$tag = new MailchimpMarketing\Model\List7();
$tag->setName("MegaInfluencer");
$tag->setStaticSegment(["dolly.parton@example.com", "rihanna@example.com"]);

try {
$response = $Mailchimp->lists->createSegment($list_id, $tag);
echo "Tag successfully created! Your tag id is " . $response->getId();
} catch (MailchimpMarketing\ApiException $e) {
echo $e->getMessage();
}

You may also be interested in creating surveys in Mailchimp or working with your own html template in the Mailchimp visual editor.

We wish you successful integrations!