Getting a grip on gibbon

If your running a website then there's a high probability you'll need a mailing list to keep your users up to date with the latest news, offers, features, etc. I've been a fan of MailChimp for years, but until recently had never had the need to integrate it with Rails.

After doing quite a bit of research into the possible gems out there, and even considering writing my own I finally settled on the Gibbon gem. However, with that said, it wasn't quite as straight forward as it should have been to implement. This is largely due to the fact I couldn't find a simple "how-to" tutorial, so I thought I'd write up my experience here.

Getting started

As usual you'll need to add the gem to your Gemfile to begin with. At the time I'm writing this article MailChimp have just released V2 of their API and Gibbon are working with v0.5. So to take advantage of all of this goodness you'll need to make sure you are using the latest verion by declaring that the gem is downloaded from the gihub page

gem 'gibbon', git: 'git://github.com/amro/gibbon.git'

Now if your reading this sometime in the future (hello!) then things may have changed and you'll probably no longer need to add that "git"  bit. I had loads of API errors popping up until I realised that I was working with the wrong syntax for the version I wanted - you've been warned!

Once you have the gem installed you can set up and initializer, this is where you declare your Mailchimp API key. Now if you havent got one of those yet, or a Mailchimp account then go ahead and sign up and then grab an API key - don't worry I'll still be here when you get back.

All done? Good, then I'll continue...

In your 'config/initializers' folder create a new file called 'gibbon.rb' and paste in the following - your going to have to put your api_key in there though...

Gibbon::API.api_key = "YOUR_API_KEY_GOES_HERE"
Gibbon::API.timeout = 15
Gibbon::API.throws_exceptions = false

Save the file and then restart your server if it's already running.

Now what?

So in my case I wanted users to be able to tick a checkbox when registering for the site and then give them the option to subscribe/unsubscribe from within their profile. I decided the best way to handle this was to add a column to the user table called "mailchimp" As I'm using PostgresDB I created a new migration to add the new column to my existing User model. This was a boolean value so that a User was either subscribed or unsubscribed (true of false). Then in my form all I needed was a checkbox tag.

<%= f.check_box :mailchimp =%>
<%= f.label :mailchimp, "Sign up to our newsletter" =%>

I decided to put the method that controlled subscription inside the User.rb model. In the model I had already added the :mailchimp attribute to the attr_accessible list, so then I could create a method that I called after a User model was saved.

after_save :mailchimp_status

The method looks like this...

def mailchimp_status
  @mailchimp_list_id = "YOUR_LIST_ID"
  @gb = Gibbon::API.new
  if self.mailchimp == true
    @gb.lists.subscribe({
    :id => @mailchimp_list_id,
    :email => {:email => self.email},
    :merge_vars => {
      :FNAME => self.name_first,
      :LNAME => self.name_last
    },
    :double_optin => false,
    :send_welcome => true
  })
  elsif self.mailchimp == false
    @gb.lists.unsubscribe({
    :id => @mailchimp_list_id,
    :email => {:email => self.email},
    :delete_member => true,
    :send_goodbye => true,
    :send_notify => false
  })
  end
end

This method looks at the :mailchimp attribute and if it is true, signs the user up to the list, if it’s false then it removes them. You can find out more about the subscribe and unsubscribe API calls on the Mailchimp Documentation, but the way that the Gibbon gem taps in to it means that the code we have to write is very minimal.

There is obviously a lot more you could do with this and Rails ninjas out there will probably be able to point out more efficient, better ways of doing this but for my needs, and for now, it works and gets the job done.

I hope that this post helps you out if your looking to integrate Mailchimp with your next Rails app, let me know how you get on by contacting me on twitter.