MailChimp | API Docs

<!DOCTYPE html> <html> <head><script type="text/javascript" src="https://web-static.archive.org/_static/js/bundle-playback.js?v=7YQSqjSh" charset="utf-8"></script> <script type="text/javascript" src="https://web-static.archive.org/_static/js/wombat.js?v=txqj7nKC" charset="utf-8"></script> <script>window.RufflePlayer=window.RufflePlayer||{};window.RufflePlayer.config={"autoplay":"on","unmuteOverlay":"hidden"};</script> <script type="text/javascript" src="https://web-static.archive.org/_static/js/ruffle/ruffle.js"></script> <script type="text/javascript"> __wm.init("https://web.archive.org/web"); __wm.wombat("http://apidocs.mailchimp.com:80/webhooks/","20130429080045","https://web.archive.org/","web","https://web-static.archive.org/_static/", "1367222445"); </script> <link rel="stylesheet" type="text/css" href="https://web-static.archive.org/_static/css/banner-styles.css?v=p7PEIJWi" /> <link rel="stylesheet" type="text/css" href="https://web-static.archive.org/_static/css/iconochive.css?v=3PDvdIFv" />  <title>MailChimp | API Docs</title>  <link href="/web/20130429080045cs_/http://apidocs.mailchimp.com/c/site.css" rel="stylesheet" type="text/css"/> </head> <body> <div class="sidebar"> <header class="line"> <a id="logo" href="https://web.archive.org/web/20130429080045/http://mailchimp.com/"> <img height="47" width="178" alt="MailChimp" src="/web/20130429080045im_/http://apidocs.mailchimp.com/i/newlogo.png"/> </a> </header> <aside id="sidebar" class="unit side"> <div class="ab"> <form id="st"> <input type="text" id="st-search-input" class="st-search-input"/> </form> <script type="text/javascript"> var Swiftype = window.Swiftype || {}; (function() { Swiftype.key = '8roboHQKbktmvSy9na82'; Swiftype.inputElement = '#st-search-input'; Swiftype.resultContainingElement = '#st-results-container'; Swiftype.attachElement = '#st-search-input'; Swiftype.renderStyle = "new_page"; Swiftype.resultPageURL = "/search/" var script = document.createElement('script'); script.type = 'text/javascript'; script.async = true; script.src = "//web.archive.org/web/20130429080045/http://swiftype.com/embed.js"; var entry = document.getElementsByTagName('script')[0]; entry.parentNode.insertBefore(script, entry); }()); </script> <nav id="nav" role="navigation"> <ul> <li class="section"> <a href="/web/20130429080045/http://apidocs.mailchimp.com/gettingstarted/connectivity.php">Getting Started</a> <ul> <li><a href="/web/20130429080045/http://apidocs.mailchimp.com/gettingstarted/connectivity.php">General Connectivity</a></li> <li><a href="/web/20130429080045/http://apidocs.mailchimp.com/gettingstarted/serialized_http_arrays.php">Serializing Arrays</a></li> <li><a href="/web/20130429080045/http://apidocs.mailchimp.com/gettingstarted/timeouts.php">Timeouts</a></li> </ul> </li> <li class="section"> <a href="/web/20130429080045/http://apidocs.mailchimp.com/api/how-to/basic-subscribe.php">How To</a> <ul> <li><a href="/web/20130429080045/http://apidocs.mailchimp.com/api/how-to/basic-subscribe.php">Basic Subscribe Form</a></li> <li><a href="/web/20130429080045/http://apidocs.mailchimp.com/api/how-to/serializing.php">Serializing Data</a></li> <li><a href="/web/20130429080045/http://apidocs.mailchimp.com/api/how-to/transactional-campaigns.php">Transactional Email</a></li> <li><a href="/web/20130429080045/http://apidocs.mailchimp.com/api/how-to/sync-you-to-mailchimp.php">Syncing Changes from You to MailChimp</a></li> <li><a href="/web/20130429080045/http://apidocs.mailchimp.com/api/how-to/sync-mailchimp-to-you.php">Syncing Changes from MailChimp to You</a></li> <li><a href="/web/20130429080045/http://apidocs.mailchimp.com/api/how-to/forward-to-a-friend.php">Reproducing Forward-to-Friend Links</a></li> <li><a href="/web/20130429080045/http://apidocs.mailchimp.com/api/how-to/ecommerce.php">Integrating Ecommerce functionality</a></li> </ul> </li> <li class="section"> <a href="/web/20130429080045/http://apidocs.mailchimp.com/api/downloads/">Downloads & API Wrappers</a> <ul> <li><a href="/web/20130429080045/http://apidocs.mailchimp.com/api/downloads/">Standard API</a></li> <li><a href="/web/20130429080045/http://apidocs.mailchimp.com/webhooks/downloads/">Webhooks</a></li> <li><a href="/web/20130429080045/http://apidocs.mailchimp.com/export/downloads/">Export</a></li> <li><a href="/web/20130429080045/http://apidocs.mailchimp.com/api/example-code/">Example Code</a></li> </ul> </li> <li class="section"><a href="/web/20130429080045/http://apidocs.mailchimp.com/api/">MailChimp API</a> <ul> <li><a href="/web/20130429080045/http://apidocs.mailchimp.com/api/1.3/">v1.3</a></li> <li><a href="/web/20130429080045/http://apidocs.mailchimp.com/api/1.2/">v1.2</a></li> <li><a href="/web/20130429080045/http://apidocs.mailchimp.com/api/1.1/">v1.1</a></li> <li><a href="/web/20130429080045/http://apidocs.mailchimp.com/api/changelog.php">changelog</a></li> </ul> </li> <li class="section"> <a href="https://web.archive.org/web/20130429080045/http://help.mandrill.com/" target="_blank">Mandrill SMTP/API</a> </li> <li class="section"> <a href="/web/20130429080045/http://apidocs.mailchimp.com/export/">Export API</a> <ul> <li><a href="/web/20130429080045/http://apidocs.mailchimp.com/export/1.0/">v1.0</a></li> </ul> </li> <li class="section"> <a href="/web/20130429080045/http://apidocs.mailchimp.com/webhooks/">Webhooks</a> </li> <li class="section"> <a href="/web/20130429080045/http://apidocs.mailchimp.com/oauth2/">OAuth2</a> </li> <li class="section"><a href="/web/20130429080045/http://apidocs.mailchimp.com/partnerapi/">Partner API</a> <ul> <li><a href="/web/20130429080045/http://apidocs.mailchimp.com/partnerapi/1.3/">v1.3</a></li> </ul> </li> <li class="section"> <a href="/web/20130429080045/http://apidocs.mailchimp.com/api/faq/">FAQ</a> </li> <li class="section"> <a href="/web/20130429080045/http://apidocs.mailchimp.com/help/">Support</a> </li> </ul> </nav> </div> </aside> </div> <div class="container"> <header class="line "> <div class="unit"> <div class=""> <hgroup class="in"> <h1><a href="/web/20130429080045/http://apidocs.mailchimp.com/">API Documentation</a></h1> </hgroup> </div> </div> <div class="right"> <div class=""> <a href="https://web.archive.org/web/20130429080045/https://login.mailchimp.com/" class="login">Log In <span></span></a> </div> </div> </header> <section class="line wrapper "> <div id="main"> <div class="in ab double"> <div> <section> <div class="padtop main" data-swiftype-index="true"> <div> <div class=" nosideborders"> <div> <h1>What are Webhooks?</h1> <p>Webhooks allow you to collect information about events as they happen in near real-time. Provide a URL, select when and where you want that URL to receive data about events on your list, and we'll send it to you as the events take place</p> <p> For general reading on Webhooks, read the <a href="https://web.archive.org/web/20130429080045/http://www.webhooks.org/" target="_blank">PBWiki Webhooks page</a>. </p> <p> To test our Webhooks before setting up scripts, the <a href="https://web.archive.org/web/20130429080045/http://requestb.in/" target="_blank">RequestBin</a> tool is an excellent utility that helps you see data come across as various events happen in our system. </p> <p> <strong>Need help getting a script started?</strong> We have some contributions in the <a href="/web/20130429080045/http://apidocs.mailchimp.com/webhooks/downloads/">downloads section</a> </p> <h2 class="margintop">Configuring Webhooks</h2> <p>Webhooks are configured from your MailChimp account. Here are the basic steps:</p> <ol class="simplelist"> <li> <a href="https://web.archive.org/web/20130429080045/https://admin.mailchimp.com/" target="_blank">Log in</a> to your MailChimp account</a> </li> <li>Navigate to your <strong>Lists</strong></li> <li>Click <strong>View Lists</strong> on the list you want to configure</li> <li>Click the <strong>List Tools</strong> menu option at the top</li> <li>Click <strong>Webhooks</strong></li> </ol> <p>Configuration is simple: Enter a <strong>valid url</strong> for us to contact, then select the events and event sources (see below for descriptions) you want to have sent to you.</p> <h2 class="margintop">Securing Webhooks</h2> <p>We currently support either HTTP or HTTPS urls, so you can have security by using an SSL-enabled url. But keep in mind that your endpoint is going to be wide-open on the internet, and you might not want others to be able to submit random data to your systems. At this time, aside from trying to keep the URL private, our best suggestion is to simply include a secret key in the URL your provide and check that GET parameter in your scripts.</p> <h2 class="margintop">Supported Events</h2> <p>Our Webhooks implementation allows a wide variety of options for the events you want to capture, based on their sources. We support the following events: <ul class="simplelist bullets "> <li>Subscribes</li> <li>Unsubscribes</li> <li>Profile Updates</li> <li>Email Address Changes</li> <li> <a href="https://web.archive.org/web/20130429080045/http://eepurl.com/gY52" target="_blank">Cleaned</a> Emails </li> <li>Campaign Sending status (can not be limited by source)</li> </ul> </p> <h2 class="margintop">Event Sources</h2> <p>You can also select the sources you want to be notified about where changes are arriving from. We support these sources of changes: <ul class="simplelist bullets buttom30"> <li>Users via the list-manage.com forms</li> <li>Admins via our web app</li> <li>API calls</li> </ul> </p> <h2 class="margintop">Event Data</h2> <p> When an event occurs that you have turned on, we'll send a <code>HTTP POST</code> request to the URL you've specified. If that URL is unavailable or takes too long to respond (more than 15 seconds), we'll cancel the request and try again later. Retries happen at increasing intervals over the course of one hour and 15 minutes. Those time frames may be tweaked as we receive feedback from users. </p> <p> We'll return various data based on each event. Below is sample data for each event. You can also see this using the <a href="https://web.archive.org/web/20130429080045/http://requestb.in/">RequestBin</a> tool mentioned above. Generally speaking, you'll see each event has a type and a fired_at field to help you track the type of event and get a timestamp (in GMT) for the event. </p> <p>This is sample data to show you the fields returned鈥攖he POST request actually sends key/value pairs, just like a normal HTML Form Submission </p> <h2 class="margintop">Subscribes</h2> <pre> "type": "subscribe", "fired_at": "2009-03-26 21:35:57", "data[id]": "8a25ff1d98", "data[list_id]": "a6b5da1054", "data[email]": "api@mailchimp.com", "data[email_type]": "html", "data[merges][EMAIL]": "api@mailchimp.com", "data[merges][FNAME]": "MailChimp", "data[merges][LNAME]": "API", "data[merges][INTERESTS]": "Group1,Group2", "data[ip_opt]": "10.20.10.30", "data[ip_signup]": "10.20.10.30" </pre> <h3>Unsubscribes</h3> <p>"action" will either be "unsub" or "delete". The reason will be "manual" unless caused by a spam complaint - then it will be "abuse"</p> <pre> "type": "unsubscribe", "fired_at": "2009-03-26 21:40:57", "data[action]": "unsub", "data[reason]": "manual", "data[id]": "8a25ff1d98", "data[list_id]": "a6b5da1054", "data[email]": "api+unsub@mailchimp.com", "data[email_type]": "html", "data[merges][EMAIL]": "api+unsub@mailchimp.com", "data[merges][FNAME]": "MailChimp", "data[merges][LNAME]": "API", "data[merges][INTERESTS]": "Group1,Group2", "data[ip_opt]": "10.20.10.30", "data[campaign_id]": "cb398d21d2", "data[reason]": "hard"</pre> <h3>Profile Updates</h3> <pre> "type": "profile", "fired_at": "2009-03-26 21:31:21", "data[id]": "8a25ff1d98", "data[list_id]": "a6b5da1054", "data[email]": "api@mailchimp.com", "data[email_type]": "html", "data[merges][EMAIL]": "api@mailchimp.com", "data[merges][FNAME]": "MailChimp", "data[merges][LNAME]": "API", "data[merges][INTERESTS]": "Group1,Group2", "data[ip_opt]": "10.20.10.30" </pre> <h3>Email Address Changes</h3> <p>Note that you will always receive a Profile Update at the same time as an Email Update</p> <pre> "type": "upemail", "fired_at": "2009-03-26\ 22:15:09", "data[list_id]": "a6b5da1054", "data[new_id]": "51da8c3259", "data[new_email]": "api+new@mailchimp.com", "data[old_email]": "api+old@mailchimp.com" </pre> <h3>Cleaned Emails</h3> <p><strong>Reason</strong> will be one of "hard" (for hard bounces) or "abuse"</p> <pre> "type": "cleaned", "fired_at": "2009-03-26 22:01:00", "data[list_id]": "a6b5da1054", "data[campaign_id]": "4fjk2ma9xd", "data[reason]": "hard", "data[email]": "api+cleaned@mailchimp.com" </pre> <h3>Campaign Sending Status</h3> <pre> "type": "campaign", "fired_at": "2009-03-26 21:31:21", "data[id]": "5aa2102003", "data[subject]": "Test Campaign Subject", "data[status]": "sent", "data[reason]": "", "data[list_id]": "a6b5da1054" </pre> </div> </div> <div> </div> </div> </div> </section> </div> </div> </div> </section> <footer> <div class="footer-content"> <div class="line"> <div class="unit size1of4"> <div class="in"> <h5>About Us</h5> <ul> <li> <a href="https://web.archive.org/web/20130429080045/http://mailchimp.com/about"> About MailChimp </a> </li> <li> <a href="https://web.archive.org/web/20130429080045/http://mailchimp.com/about/jobs"> Jobs </a> </li> <li> <a href="https://web.archive.org/web/20130429080045/http://mailchimp.com/about/customer-stories"> Customer Stories </a> </li> <li> <a href="https://web.archive.org/web/20130429080045/http://mailchimp.com/about/press-resources"> Press Resources </a> </li> <li> <a href="https://web.archive.org/web/20130429080045/http://mailchimp.com/about/press-releases"> Press Releases </a> </li> <li> <a href="https://web.archive.org/web/20130429080045/http://mailchimp.com/about/integration-fund"> Integration Fund </a> </li> <li> <a href="https://web.archive.org/web/20130429080045/http://mailchimp.com/about/brand-assets"> Brand Assets </a> </li> </ul> </div> </div> <div class="unit size1of4"> <div class="in"> <h5>Connect With Us</h5> <ul> <li> <a href="https://web.archive.org/web/20130429080045/http://connect.mailchimp.com/"> Integrations & Plugins </a> </li> <li> <a href="https://web.archive.org/web/20130429080045/http://mailchimp.com/api"> MailChimp API </a> </li> <li> <a href="https://web.archive.org/web/20130429080045/http://mailchimp.com/labs"> MailChimp Labs </a> </li> </ul> </div> </div> <div class="unit size1of4"> <div class="in"> <h5>Contact Us</h5> <ul> <li> <a href="https://web.archive.org/web/20130429080045/http://kb.mailchimp.com/contact"> Contact MailChimp </a> </li> <li> <a href="https://web.archive.org/web/20130429080045/http://mailchimp.com/contact/partnerships"> Partner With Us </a> </li> <li> <a href="https://web.archive.org/web/20130429080045/http://mailchimp.com/contact/abuse"> Abuse Desk </a> </li> <li> <a href="https://web.archive.org/web/20130429080045/http://status.mailchimp.com/"> MailChimp Status </a> </li> <li> <a href="https://web.archive.org/web/20130429080045/http://experts.mailchimp.com/"> Find an Expert </a> </li> </ul> </div> </div> <div class="unit size1of4"> <div class="in"> <h5>Legal Info</h5> <ul> <li> <a href="https://web.archive.org/web/20130429080045/http://mailchimp.com/legal/terms"> Terms of Use </a> </li> <li> <a href="https://web.archive.org/web/20130429080045/http://mailchimp.com/legal/privacy"> Privacy Policy </a> </li> <li> <a href="https://web.archive.org/web/20130429080045/http://mailchimp.com/legal/copyright"> Copyright Policy </a> </li> </ul> </div> </div> </div> <div class="line"> <div class="colophon"> <p>© 2001-2012 All Rights Reserved. MailChimp® is a registered trademark of The Rocket Science Group</p> </div> </div> </div> </footer> </div>  <script src="https://web.archive.org/web/20130429080045js_/http://code.jquery.com/jquery-1.7.2.min.js"></script> <script src="/web/20130429080045js_/http://apidocs.mailchimp.com/js/gen.js"></script> <script type="text/javascript"> var _gaq = _gaq || []; _gaq.push(['_setAccount', 'UA-329148-81']); _gaq.push(['_setDomainName', '.mailchimp.com']); _gaq.push(['_addIgnoredRef', 'mailchimp.com']); _gaq.push(['_addIgnoredOrganic', 'mailchimp.com']); _gaq.push(['_trackPageview']); (function() { var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true; ga.src = ('https:' == document.location.protocol ? 'https://web.archive.org/web/20130429080045/https://ssl' : 'https://web.archive.org/web/20130429080045/http://www') + '.google-analytics.com/ga.js'; var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s); })(); </script> </body> </html>

CINXE.COM

MailChimp | API Docs