================ Django Mailchimp ================ This is an integrated app for Django dealing with the Mailchimp mailing list system. Quick start guide: ------------------ Installation: ************* 1. Install django_mailchimp:: pip install django_mailchimp 2. Add an ``MAILCHIMP_API_KEY`` to your settings.py with your mailchimp API key as the value (obviously) 3. Add ``mailchimp`` to your project's list of INSTALLED_APPS 4. To start using the API, you should start by using utils.get_connection(). This will use the API_KEY you just defined in settings.py Subscribing a user to a list: ***************************** 1. To get the list:: list = mailchimp.utils.get_connection().get_list_by_id(<list key id>) 2. Now add a member to the mailing list:: list.subscribe('example@example.com',{'EMAIL':'example@example.com'}) Those pesky merge vars: ----------------------- General info: ************* Mailchimp is a quite generic service. As such, it needs to store information on people who subscribe to a list, and that information is specific to this very list! So to help you build dynamic forms (presumabely), mailchimp added the merge_vars. They are, basically, a dictionnary showing infromation and meta-information defined for each piece of information. Here's what the default set of merge vars look like (ona brand new list with default options):: [ { 'field_type': 'email', 'name': 'Email Address', 'show': True, 'default': None, 'req': True, 'public': True, 'tag': 'EMAIL', 'helptext': None, 'order': '1', 'size': '25' },{ 'field_type': 'text', 'name': 'First Name', 'show': True, 'default': '', 'req': False, 'public': True, 'tag': 'FNAME', 'helptext': '', 'order': '2', 'size': '25' },{ 'field_type': 'text', 'name': 'Last Name', 'show': True, 'default': '', 'req': False, 'public': True, 'tag': 'LNAME', 'helptext': '', 'order': '3', 'size': '25' } ] As you can see, it's a list of 3 dictionnaries, each containing several fields that you should use to build your user interface with (since you're using this app, that means your Django form). Obtaining them: *************** You can recreate this list using the following API call:: list = mailchimp.utils.get_connection().get_list_by_id(<The list's key ID>) print list.merges Using them: *********** When you make a post to mailchimp, you need to pass merge_vars. For example, in a new list created with the default settings on the mailchimp website, the following call adds a member to a list (with a little more info than our bare minimum example up there):: list = mailchimp.utils.get_connection().get_list_by_id(<The list's key ID>) list.subscribe('example@example.com',{'EMAIL':'example@example.com', 'FNAME': 'Monthy', 'LNAME':'Pyhtons'}) Note the use of the 'tag' field as the key for fields (why they didn't call it 'key' or 'id' is beyond comprehension). Create a view: -------------- We'll now try to move up the stack and create the necessary elements to make a useable mailchimp interface Fire up your favorite editor and open your views.py. Put in the following snippet of code:: MAILCHIMP_LIST_ID = 'spamspamspamspameggsspamspam' # DRY :) REDIRECT_URL_NAME = '/mailing_list_success/' def add_email_to_mailing_list(request): if request.POST['email']: email_address = requst.POST['email'] list = mailchimp.utils.get_connection().get_list_by_id(MAILCHIMP_LIST_ID) list.subscribe(email_address,{'EMAIL':email_address}) return HttpResponseRedirect('/mailing_list_success/') else: return HttpResponseRedirect('/mailing_list_failure/') Of course, if you feel redirecting the user is not the right approach (handling a form might be a good idea), feel free to adapt this simple example to your needs :p