Working With The MailChimp API In .NET: The Basics

This is the second in a series of articles on using the MailChimp.NET.V3 wrapper to access the MailChimp REST API in .NET

The first thing we need to do to begin working with the MailChimp API in .NET is obtain an API key from MailChimp.

API keys are free (as in “free beer”) and can be obtained for any MailChimp account in good standing, including free (again, as in “free beer”) accounts.

Once we have a MailChimp API key, we’re ready to install the MailChimp.NET.V3 NuGet package into a Visual Studio 2015 project.

As noted in Part 1 of this series, I will be using ASP.NET MVC as my project type. However, the fundamentals of obtaining an API key and installing a NuGet package are the same, regardless of Visual Studio project type.

These two videos go over the process of obtaining a MailChimp API key (first video) and installing the MailChimp.NET.V3 NuGet package (second video):

An important note about API security

Before we get started, a word of caution: A MailChimp API key grants full access to your MailChimp account.

A valid key allows its bearer to do pretty much anything via the API that can be done via the Dashboard: Create a campaign, add / remove users to a list, unsubscribe users from a list, edit a template, etc.

Unfortunately, there’s no way to make a key that’s restricted to certain API endpoints or specific verbs (e.g., you can’t have a read-only key that can only retrieve campaign histories).

In other words, an API key in the wrong hands can put you in quite a pickle. Be super-careful about who has access to your API keys and how you store them.

The MailChimpManager class

With API key in hand and MailChimp.NET.V3 NuGet package installed, we’re ready to start coding.

Central to the MailChimp.NET.V3 wrapper is the MailChimpManager class.

Like the TwitterContext class in Linq2Twitter, MailChimpManager is a context. It has a number of methods that represent the individual endpoints of the MailChimp API; and it completely abstracts the authentication process.

In .NET, a context is a class that contains other objects and data which support all the numerous subroutines and tasks associated with, in this case, creating, sending, retrieving and parsing a REST request and response.

Therefore, we’re up and running in our demo project by first adding our API key to our web.config file:

<configuration>
    <appSettings>
        <add key="MailChimpApiKey" value="kh4lnw6gexwd1ba6fwzd91j9sdimfb30-us4" />
    </appSettings>
</configuration>

So long as the key is named MailChimpApiKey, we need do nothing else to create as many instances of MailChimpManager as we like. The mere presence of your API key in your web.config will allow MailChimp.NET.V3 to wire up your connections to the MailChimp API automagically.

Declare MailChimpManager in high scope

Since MailChimpManager is, again, really a context, it makes the most sense to declare it in a fairly high scope. That is, we usually want to declare these MailChimpManager contexts as members of a class, rather than invoking a new instance in every method.

That way, we can recycle the same instance for multiple API calls, saving the overhead and time needed to provision a new context with every request.

In this case, I’m going to have a single page controller for my ASP.NET MVC solutution, called MailChimpController; therefore, I will declare a single private MailChimpManager for that entire controller. It will handle all the different ActionResults for that MailChimpController.

using System.Web.Mvc;
using MailChimp.Net;

namespace MailChimpNet.Controllers
{
    public class MailChimpController : Controller
    {
        private static MailChimpManager Manager = new MailChimpManager();
    }
}

And now, I can apply that one Manager instance to several different methods, like so:

using System.Threading.Tasks;
using System.Web.Mvc;
using MailChimp.Net;

namespace MailChimpNet.Controllers
{
    public class MailChimpController : Controller
    {
        private static MailChimpManager Manager = new MailChimpManager();

        public async Task<ActionResult> Index()
        {
            var model = await Manager.Lists.GetAllAsync();
            return View(model);
        }

        public async Task<ActionResult> Members()
        {
            var model = await Manager.Members.GetAllAsync("048eevbxad");
            return View(model);
        }
    }
}

We’ll get into the specifics of what these methods are in upcoming posts.

The entirety of the MailChimp.NET.V3 wrapper library runs async. This is not so much of a problem in an ASP.NET MVC application like I’m demonstrating, since ActionResults can be returned asynchronously, and as a Task, directly to the view engine. But it can be problematic if you’re trying to tie this into non-async code.

For help on that, check out my post, Posting Status Updates To Twitter Via LinqToTwitter: Part 4, Async Operations.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.

  • Check out the Commenting Guidelines before commenting, please!
  • Want to share code? Please put it into a GitHub Gist, CodePen or pastebin and link to that in your comment.
  • Just have a line or two of markup? Wrap them in an appropriate SyntaxHighlighter Evolved shortcode for your programming language, please!