Acts_As_Mailchimp

This plugin has been degraded, and is no longer being supported, since it requires more code than interacting with the Hominid gem directly.

Hominid Installation

Install the Hominid gem.

sudo gem install bgetting-hominid

Set the dependency for your Rails application in config/environments.rb:

config.gem "bgetting-hominid", :version => '>= 1.1.2', :lib => 'hominid'

You will also need a MailChimp account, which can be set up for free. Once set up, you will need to generate an API key. Hominid expects to find a configuration file at config/hominid.yml, which will contain your Mailchimp account information.

Use

Basic usage for adding, removing and updating a recipient in Mailchimp is as follows:

app/controllers/application.rb

def add_to_mailchimp(list_name, newsletter_email)
	hominid ||= Hominid.new
  list_id ||= hominid.lists.find {|l| l['name'] == list_name}['id']
  hominid.subscribe(list_id, newsletter_email, {}, 'html')
rescue
	false
end

def remove_from_mailchimp(list_name, newsletter_email)
	hominid ||= Hominid.new
  list_id ||= hominid.lists.find {|l| l['name'] == list_name}['id']
  hominid.unsubscribe(list_id, newsletter_email)
rescue
	false
end

def update_mailchimp(list_name, previous_email, newsletter_email)
  hominid ||= Hominid.new
  list_id ||= hominid.lists.find {|l| l['name'] == list_name}['id']
  hominid.update_member(list_id, previous_email, {:EMAIL => newsletter_email}, 'html')
rescue
  false
end

You can add hashes of attributes to the methods if you need them in order to work with additional attributes of your Mailchimp list, such as first name, last name and custom fields.

Syncing Your Rails Application

You can sync your mailing list at Mailchimp with your application database using List Web Hooks. To set up a web hook for a list in Mailchimp, follow these instructions:

1. Log in to your Mailchimp account.
2. Click on the “Lists” tab.
3. Click “view list” for the list you want to work with.
4. Click on “list tools” at the top.
5. Click on “web hooks” on the tools page.

Basically, a web hook is a POST request that will be automatically sent from Mailchimp to a URL of your choice when certain events occur. You can take a look at the documentation to adjust your particular web hook, but the defaults are fine for demonstration.

To start, enter the URL in your application that you want Mailchimp to send requests to:

http://myapp.com/mailchimp?secret=123456

As you can see, we also include a secret value since we want to be able to determine between a request from Mailchimp and a request from somewhere else. Remember, this URL will be exposed (even though you will keep it a secret) to the world, so requests need to be verified. In this case, we would just have something like this in the controller:

unless params[:secret] == '123456'
	...
end

You can see the types of responses that each action will send by visiting the Mailchimp documentation for web hooks. Currently the web hooks can be fired when the following events occur:

• Subscribes
• Unsubscribes
• Profile updates
• Email address change
• Cleaned emails

You will want to account for each of these in the controller that you create to receive these POST requests. Sometimes you may not have to worry about all of them, such as if your application handles all subscribes to the list, then you probably don’t have to process subscribes from the web hook. Especially if your user model requires more data than is supplied by the web hook. The documentation also contains sample output for each of these events. A sample controller action might look like this:

def index
  if params[:secret] == "123456"
    case params[:type]      
    when "unsubscribe"
      user = User.find_by_email(params[:data][:email])
			remove_from_mailchimp("My Email List", user.email)
    when "profile"
      user = User.find_by_email(params[:data][:email])
			user.first_name = params[:data][:merges][:FNAME]
			user.last_name = params[:data][:merges][:LNAME]
			user.save
    when "upemail"
      user = User.find_by_email(params[:data][:old_email])
			user.email = params[:data][:new_email]
    end
  end
end

Updates

June 2009

Discontinued the Acts_As_Mailchimp plugin in order to promote the use of the Hominid gem. There was no real reason that these methods needed to be coupled to a model, and it requires much less code to simply use the Hominid gem directly in your Ruby application. Hopefully nobody is too upset, but this whole thing seemed overly complicated for no real reason.

April 2009

Updated the README to use web hooks rather than the older method of syncing an application with the Mailchimp database. This will probably be updated again when the Hominid gem is updated.

March 2009

This plugin has been overhauled to work with the new Hominid GemPlugin, which is expected to be completed by the end of April 2009. In the meantime, there may be some inconsistencies and bugs in the plugins. I’ll try and make an announcement when the Hominid GemPlugin is completed, and when the Acts_As_Mailchimp plugin has been completely updated as well.

September 2008

MailChimp updated their API from Version 1.0 to Version 1.1 in August 2008. We are continuing to update acts_as_mailchimp in order to keep it current, and have issued the following changes as of September 2008:

• API calls are now being made to Version 1.1 of the MailChimp API.
• add_to_chimp changed to add_to_mailchimp.
• remove_from_chimp changed to remove_from_mailchimp.
• update_chimp_ changed to update_mailchimp.