Retrieving List Data

Now that you've learned how the API works, let's talk about how to make API calls. 0:00 One of our most frequently used API calls is the subscribe call. 0:04 Subscribing new members to a list in your MailChimp account is an essential part of 0:09 setting up whether you're building a custom sign up form, connecting a third 0:12 party CRM to MailChimp, or just syncing an existing database of emails. 0:16 Here's everything you'll need to make your API calls. 0:22 First, you'll need a MailChimp API key. 0:25 We've gone over how to create a new key and 0:27 where to get it, if you don't have it handy. 0:29 Next, you'll need a MailChimp list ID. 0:31 A list ID can be gathered via the API or through the application. 0:34 More on this in a second. 0:38 You'll also need your new subscriber's email address. 0:39 In order to add a new member to a list in MailChimp, 0:42 they have to have a unique email address. 0:44 Finally, you also have the option to pass in merge field or 0:46 merge tag information like first name and last name. 0:49 This is subscriber specific information and 0:53 can be recalled dynamically in an email campaign. 0:55 And here's the workflow we'll use, first we'll make a get request to the list 0:58 endpoint, and get all of our list information. 1:02 Then we'll make a second get request to the specific list 1:05 to see that list information. 1:08 Then we'll make a get request to the list slash list ID 1:11 slash members endpoint to view the existing subscribers. 1:14 And finally, we'll make a post request to the list slash list ID slash member's 1:18 endpoint, with information about the new subscriber and adding them to the list. 1:22 This specific workflow won't be necessary every time. 1:27 You'll make a few extra calls to get familiar with the MailChimp API and 1:30 get the information you need. 1:33 Since you already have your API key for 1:35 this account, look at the list where you want to subscribe the new member. 1:37 Within MailChimp, each list is treated as its own separate entity, and 1:41 uniquely identified with its ID. 1:45 There are a couple ways to find the list ID. 1:47 To view your list ID within a MailChimp account, 1:51 click on the list tab in the navigation bar. 1:53 Find the list you wanna use and in the settings drawer choose Settings. 1:57 At the bottom of the settings page you'll see your list unique ID. 2:02 You can also find this information under list name & defaults. 2:06 Alternatively, if you're building an app or just writing a script, 2:12 you may want a more programmatic way to go about finding your list and their IDs. 2:16 That's where the MailChimp API does the heavy lifting for you. 2:20 With a get request you can retrieve a collection of 2:24 lists within a MailChimp account. 2:27 For all API calls you'll need an API key to tell MailChimp who you are. 2:30 However, depending on what sort of information you're sending or 2:34 receiving, you may need to point towards specific resources or 2:37 include additional parameters. 2:41 For instance, if you wanted to create a new campaign, you'd need to send 2:44 information about the subject line, from address, and actual HTML content. 2:47 If you just wanted to get a list of your existing campaigns, 2:53 you don't need all of that information. 2:55 In short, it's always worth having a look at the documentation 2:58 to see what's required for a particular API call. 3:01 If all you need is to get information about your lists, 3:05 the only thing that's required is your MailChimp API key. 3:08 If you're using one of MailChimp's API wrappers, 3:11 the wrapper handles the interaction with MailChimp behind the scenes. 3:14 Curl, on the other hand, means you are going to do everything manually. 3:17 This includes requesting the correct URL, making sure all of your parameters 3:20 are included and valid, and using the correct type of HTTP request. 3:25 For this course, you'll be using terminal for Mac or 3:30 command prompt on Windows to make curl requests. 3:33 If you're more comfortable with another programming language, 3:36 curl is universal enough that you should be able to find a suitable library for 3:39 your language of choice. 3:42 Our API wrappers aim to simplify the process for a number of languages as well. 3:44 To get started with Curl, open up terminal. 3:49 Curl help to make web requests without having to load up a browser like Chrome. 3:52 Instead, you can make a get request by putting the following into your 3:56 terminal window. 3:59 You'll use the command curl followed by the URL you're requesting. 4:00 If we wanted to make get request for your MailChimp list, we'd use this format. 4:04 We'll start with curl and then add in our default API URL, 4:08 which is https://us whatever your data center is. 4:12 .Api.mailchimp.com/3.0/lists. 4:18 Where the US portion of the URL is your specific data center. 4:24 3.0 is the version of the API we're using, and 4:28 lists is a specific resource that we're requesting. 4:32 Before you make this request though, you need to let MailChimp know who you are and 4:35 which account you wanna ask about. 4:39 If you don't include an API key, MailChimp will send you back an error. 4:40 You can't just throw an API key anywhere though, because MailChimp is looking in 4:46 a very specific place for this information, instead, 4:50 you'll need to create an authorization header with your curl request. 4:53 To add a header you add an argument to your curl request, 4:56 and then in quotations marks fill in the details about your header. 4:59 In this case we'll start with curl, -H for header, and 5:03 then in quotation marks we'll add authorization:apikey, 5:07 which tells us the type of authorization, and then are actual API key. 5:11 And then we'll include our URL to the list end point, 5:18 https://us10.api.mailchimp.com/3.0/lists. 5:23 Now you can successfully run this curl request for your MailChimp email list. 5:32 Depending on your account and 5:37 how many lists you have, you should see a JSON return with your list information. 5:38 Looking at the docs, you can get a feel for what data is being returned and 5:43 where you might be able to locate it. 5:46 As mentioned before, you're looking specifically for a list ID. 5:48 You may notice that there are two possible return parameters 5:51 that sound like they may be a match. 5:55 ID, and web ID. 5:57 The web ID parameter is all numbers, and it's used within the application. 5:59 Unfortunately, this doesn't uniquely identify a list across all of MailChimp. 6:03 But the ID value does. 6:07 No two lists in MailChimp will have the same ID value, so that's the one you want. 6:10 ID is referred to as list ID in the application. 6:14 Lists ID tells us which specific list you'll be sending or 6:17 pulling information from. 6:21 If you wanna get information about a specific list, 6:23 you can add an additional parameter to pull information for that list. 6:26 You'll make a get request to the specific list. 6:30 To get information about a specific list, 6:34 you'll append the list unique ID to the end of the curl request. 6:36 Picking up with our previous curl request we have the curl command, 6:39 our authorization header, and then our list URL. 6:43 Now we just add the list unique ID to the end of the URL, and 6:47 we should see that list returned. 6:52 Instead of getting information about all of the lists and 6:54 sorting through to find our match, this tells MailChimp, 6:56 we just wanna look at data for a very specific list. 6:58 You can get general data of about each list in your MailChimp account 7:01 by swapping out the ID portion at the end of the URL. 7:04 Great, now you have the information you need for your list. 7:08 But what other information that's provided that may be helpful? 7:11 Check out your documentation and 7:14 see if you can pick out some interesting values that you return with that API call. 7:15