Mad Mimi (API Key & XML)#

This example app with showcase a simple usage of scripting to parse XML. The rest of the example is pretty straightforward and might be applicable to other APIs even if they don't use XML. To make this example even more real world, we'll be implementing a real API for a real service called Mad Mimi!

Quick Preparation Checklist#

If you plan to follow along, it is recommended you set up everything beforehand and keep these resources open and ready for quick access.

Getting Started#

The first thing you'll want to do is create the app you'll be working on, this is probably the simplest thing of all! Just go to your developer apps and click the "Create App" button and enter the information.

https://cdn.zapier.com/storage/photos/5be654bc411ab0fcd7905faeb8e51d14.png

Authentication#

The first thing to do is describe how the API authenticates, you can click the Get Started button after you create your app to do that.

https://cdn.zapier.com/storage/photos/b33516a2c469757a0240f82fd68edc6b.png

If your browse the Mad Mimi developer docs you'll notice they place their authentication bits in the querystring of a URL like so: ?username={{username}}&api_key={{api_key}}. Luckily Zapier supports API Key Querystring authentication natively!

https://cdn.zapier.com/storage/photos/344629ea9b18ae7c6b347ad5b6d6abe2.png

After you choose API Key and Querystring, you'll have the option to add more Authentication fields in addition the the most basic version which is just a field for api_key which we'll add for you by default:

https://cdn.zapier.com/storage/photos/50a0a8b6711b6752bcb4f45075e63ee2.png

Since Mad Mimi requires the username in addition to api_key we can very easily Add Authentication Field for the username portion as will (which Mad Mimi sometimes refers to as email as well). You'll need to fill it out similar to this:

https://cdn.zapier.com/storage/photos/9a58e9e300ac492f919834ad5fb4c74d.png

After you save, we'll show you both fields that we'll present to the user to fill out: both username and api_key.

https://cdn.zapier.com/storage/photos/47ff914863f02d7bcdaf32c95d467220.png

Finally, you'll need to define the mapping: that is where we take the user provided authentication values and place them into the querystring using a simple JSON mapping:

https://cdn.zapier.com/storage/photos/5d3f10ad0b1711d74769896c90cd51f1.png

In case it the above screenshot is hard to read or you need some copy pasta, here are the values in the raw for the auth mapping:

{
    "username": "{{username}}",
    "api_key": "{{api_key}}"
}

Your First Trigger#

Now, authentication should be finished! The next piece is to create a test trigger that uses that authentication to confirm that it all works. It isn't uncommon to repurpose a normal trigger as a test trigger, so let's do that! The trigger we'll add is one that enumerates a new Audience List and you can read about in the Mad Mimi Audience List API documentation, let's get hopping, just click to create your first trigger:

https://cdn.zapier.com/storage/photos/e64b8bb61974202d21dbbadcbc230dba.png

After you input the trigger basics (be sure to uncheck "hide" since you are making a normal trigger at the same time), you'll have the option to create trigger fields. Since the endpoint in question doesn't need anything in addition to the standard username and api_key which Zapier will place for you automatically, so you can just skip this step:

https://cdn.zapier.com/storage/photos/4b37703b8fb3efd4027bc99fb576fc4f.png

The last bit for this trigger is placing the API URL we need to hit to get an array of audience lists, again, you can get that from Mad Mimi Audience List API documentation, it looks something like http://api.madmimi.com/audience_lists/lists.xml, just paste it in the right spot!

https://cdn.zapier.com/storage/photos/8a015e11ffb7d0ddf2fafc05b748dd28.png

The only piece we're missing is the XML parsing via our javascript scripting feature, but before we attempt to write that it's time to go test the app on the editor.

All developer apps are available immediately on your account, you can just visit your editor and use your app just like any other app Zapier supports!

Just select your app, and continue through the editor:

https://cdn.zapier.com/storage/photos/ed0e33fca1a04c9672ce0103bad5156a.png

And add your authentication in the second step:

https://cdn.zapier.com/storage/photos/9188d7f6ad72f808c4d90b1535eed5f3.png

Since all we care about is the 200 response, the test passes fine! However, we're still getting XML that we can't quite understand, you can view the HTTP logs back in the developer app overview to get an idea of what it looks like:

https://cdn.zapier.com/storage/photos/d79c8adbe50a747b260e6038461d0d67.png

And if you view the details you should see the content we got back in the response:

https://cdn.zapier.com/storage/photos/6b9e341f9bb0c5b68df0295df2dcc16b.png

Scripting Your First Trigger#

Now its time to load up the code editor! Since we called the trigger audience_list, we can write a audience_list_post_poll method to handle the otherwise successful response and convert the XML to JSON. To get started, just open up the code editor:

https://cdn.zapier.com/storage/photos/047cef3c846cda5c46e6056cb7d10fca.png

The input, code and output that works for this example is this:

Input#

<?xml version="1.0" encoding="UTF-8"?>
<lists>
  <list subscriber_count="0" display_name="" name="My Test List" id="933748"/>
</lists>

Code#

Zap = {
    audience_list_post_poll: function(bundle) {
        // use the provided dom methods with a familiar jquery interface
        xmlElements = $($.parseXML(bundle.response.content)).find('list');
        // return a list of objects that are json serializable 
        return _.map(xmlElements, function(listElement) {
            listElement = $(listElement);
            // pull off each attribute manually, place into object
            return {
                id:                 listElement.attr('id'),
                subscriber_count:   listElement.attr('subscriber_count'),
                display_name:       listElement.attr('display_name'),
                name:               listElement.attr('name'),
            };
        });
    },
};

Output#

[
    {
        "name": "My Test List",
        "display_name": "",
        "id": "933748",
        "subscriber_count": "0"
    }
]

If you want to check out more examples for post_poll methods check out our scripting documentation.

That's it for your first trigger that lives a double life as a test trigger (and will power a dynamic dropdown very shortly!). Keep reading, let's wrap up this app!

Your First Action#

The primary action we'll want to create is one that can add an audience member to a list. Of course, we'll need to provide the list and email address at minimum (which an option to expand to more fields if you like). Take a quick look at the Add audience member list in the Mad Mimi docs to get your bearings, and let's jump straight in!

https://cdn.zapier.com/storage/photos/71f185dce57d59d530246db8d0ab0dd4.png

This first thing is to define a bit of the basic information about the action, like below:

https://cdn.zapier.com/storage/photos/0f04990ac536b310571ff9e6cc5a20b6.png

Next is time for action fields! You should see a screen like this:

https://cdn.zapier.com/storage/photos/6033537bed7856447d47625362ac357f.png

Your goal is to get it looking more like:

https://cdn.zapier.com/storage/photos/7ed43b565a4281a860ecb65a36a23602.png

You can do that by adding new action fields, be sure to define the dynamic dropdown source as audience_list.id.name to reference the trigger we made earlier. That will create a dropdown that a user can easily use to power their apps. For example:

https://cdn.zapier.com/storage/photos/ffb2c892bebff26a588a84e7fd563b24.png

When you create the email action field, be sure to check the "Send In JSON" option, you'll see why when we revisit your scripts in just a moment.

Now your action fields should look something like this:

https://cdn.zapier.com/storage/photos/7ed43b565a4281a860ecb65a36a23602.png

The last step is letting us know where we should POST the data to! The URL should look something like http://api.madmimi.com/audience_lists/{{audience_list}}/add. Note, the audience_list variable in the URL: that is referencing the dynamic dropdown action field. In the interface, the URL should be be placed in this location:

https://cdn.zapier.com/storage/photos/cee53c671f37b6c9dd4dfb5c7282f78a.png

And that's it for the action definition, next up we need to convert our default application/json encoding into application/x-www-form-urlencoded, the "Send In JSON" option decides what we serialize by default, but you can always build even more complex structures from the bundle.action_fields object if you need to. We're just keeping it simple!

Default Input#

{"email":"hello@world.com"}

Code#

Zap = {
    // place other methods from earlier code here!

    audience_member_pre_write: function(bundle) {
        bundle.request.data = $.param(z.JSON.parse(bundle.request.data));
        bundle.request.headers['Content-Type'] = 'application/x-www-form-urlencoded';
        return bundle.request;
    }
};

Corrected Output#

email=hello%40world.com

Alrighty, that wraps up all the work we need to do to make this action work. You are welcome to expand action fields out past email by including first_name, last_name, country, state, etc. However, we're going to leave this example as simple as possible!

Test it out!#

If you go back to your editor and do a full page refresh, you should be able to select Mad Mimi and Add Audience Member as the action. As you scroll down to the mapping step, you should see something like:

https://cdn.zapier.com/storage/photos/9f4fff60410c8f2f13d0490c10afba9e.png

Depending on what you use as the trigger, in the test step you can load some samples and send the sample across the wire to Mad Mimi and the action you just created:

https://cdn.zapier.com/storage/photos/4c9cdcf00084bcfd66b051edac671f42.png

After you complete that, go back to your developer app and view the HTTP requests to ensure that the request got sent:

https://cdn.zapier.com/storage/photos/914e43ecde53831d2ab83e4bef7f720c.png

And its also a good idea to login to Mad Mimi and ensure you see the email there too!

https://cdn.zapier.com/storage/photos/b8201e364ce60bf211930a0a84271e24.png

With that, I give you a well-earned congratulations! You've created an example application with a mix of XML and form encoded payloads that uses API keys, scripting, and dynamic dropdowns!

↑ Was this documentation useful? Yes No
Get Help