Acts_As_Mailchimp

This is an overhaul to the old acts_as_mailchimp plugin that requires the Hominid gem.

Installation

Install as a plugin by typing: script/plugin install git://github.com/bgetting/acts_as_mailchimp.git

Prerequisites

You will need a few things to be in place before using this plugin.

Mailchimp Account

You will need to have an account set up at MailChimp. Setting up an account at MailChimp is free and you will not be charged until you actually send out emails.

Hominid Gem

You will also need to have Hominid installed as a plugin:

script/plugin install git://github.com/bgetting/hominid.git

or as a GemPlugin (recommended) by including the following in your environment.rb file:

config.gem "bgetting-hominid", :version => '~> 0.0.2', :lib => 'hominid', :source => "http://gems.github.com"

Required Fields

Acts_As_Mailchimp expects a model with the following required fields:

email:string – The email address to add/remove from a MailChimp mailing list.
email_type:string – Preferred email format. Must be either ‘html’ or ‘text’.

Additionally, the plugin allows for the following options fields, which must be added to your list first in MailChimp:

first_name:string – The first name of the user to add/remove from a MailChimp mailing list.
last_name:string – The last name of the user to add/remove from a MailChimp mailing list.

After Installation

There are a couple of things that you will need to do after installing the plugin:

If you are using the GemPlugin, make sure to create a configuration file at config/hominid.yml.
Add your MailChimp username and password for each environment that you want to use into /config/hominid.yml.
Generate a migration to add the first_name and last_name fields to the ‘User’ model (Optional).
Make any adjustments that you want to /db/migrate/add_mailchimp_fields.rb (Optional).
Migrate your database with rake db:migrate.

Usage

The following assumes that you have a model named ‘User’, which has the required email and email_type fields. Please alter to suit if you have a different schema.

Add acts_as_mailchimp anywhere in your /models/user.rb file.

Customizing

You can customize the fields that the plugin accepts to make an existing model more Chimp-like. Simply pass the fields that you would like to use along with the acts_as_mailchimp call in your ‘User’ model.


acts_as_mailchimp :email => ‘email_field’,
:type => ‘email_type_field’,
:fname => ‘first_name_field’,
:lname => ‘last_name_field’

You only need to pass in the column names that you want to override.

Methods

Once added to a model, acts_as_mailchimp adds the following methods to model instances:

user.add_to_mailchimp("list_name"): Add a user to a mailing list at MailChimp called list_name. You can set the double_opt boolean to “true” in the config/hominid.yml file to use the double opt-in feature at Mailchimp. If set to true, a confirmation email will be generated from MailChimp (and customizable in the MailChimp interface) that will ask the user to verify their desire to be added to the mailing list. They will need to click a verification link in order to be added to the list.

user.remove_from_mailchimp("list_name"): Removes a user from the specified mailing list at MailChimp.

user.update_mailchimp("list_name", "previous_email_address"): Updates a user’s information at MailChimp. The value for previous_email_address is optional, and will default to the email address in the database for that user. The idea here is that if a user changes their email address in the Rails application, MailChimp will need to old email address in order to look up the user.

Examples

The following controller examples illustrate how to use acts_as_mailchimp:

To add a user to a mailing list called “weekly_newsletter”:


@user.add_to_mailchimp(“weekly_newsletter”)

To remove a user from a mailing list called “weekly_newsletter”:


@user.remove_from_mailchimp(“weekly_newsletter”)

To update information about a user Rails 2.1 or below:


previous = params[:user][:email]
if @user.update_attributes(params[:user])

		  @user.update_mailchimp(“weekly_newsletter”, previous) if @user.email != previous

		end

To update information about a user Rails 2.1 or above:


if @user.update_attributes(params[:user])

		  @user.update_mailchimp(“weekly_newsletter”, @user.email_was) if @user.email_changed?

		end

Keep in mind that you these update examples do not make calls to the MailChimp API unless the user changes their email address. If you are integrating first_name and last_name fields as well, you will need to adjust your controller code to update MailChimp when they change either of these values as well.

Syncing Your Rails Application

One of the issues with integrating a Rails application with MailChimp is keeping the mailing list at MailChimp in sync with the information in the database of your Rails application. Depending on how your Rails application works, there are a couple of options for making sure that the two systems are synced up:

1. MailChimp sends out an email notification when users subscribe and unsubscribe to your list. You must set this up for each list in your MailChimp interface. One option is to have this email delivered to a dedicated inbox that is periodically checked by your Rails application, such as in a background process. The Rails application would then need to open up each email, determine which email addresses need to be removed or added, and then make the required changes in the database. The only reason to resort to this method is if there are multiple ways to sign up for a mailing list, where the person may not be going through the Rails application to get on the MailChimp mailing list.

2. A much easier method, and one that allows for immediate changes to your Rails application database, is to use a transparent GIF image on your “successful unsubscribe” page in the MailChimp interface. This method assumes that the only way someone can get signed up for your mailing list is through your Rails application. Since they can unsubscribe directly through MailChimp still, this technique simply notifies the Rails application when someone unsubscribes from outside the Rails application. Here is an example:

MAILCHIMP SUCCESSFUL UNSUBSCRIBE TEMPLATE

This will send a request to your application. The markup |EMAIL| will cause Mail Chimp to substitute the email address that just unsubscribed.

REMOVE CONTROLLER


def index
@listname = params[:listName]
@email = params[:email]
user = User.find_by_email(email)
@user.subscribed_weekly = 0 if @listName = “weekly_newsletter”
@user.subscribed_monthly = 0 if @listName = “monthly_newsletter”

      @user.save

    end

Since the email address has already been removed from the list in Mail Chimp, this function merely needs to update the User instance for that email address, letting the Rails application know that the user has unsubscribed directly through MailChimp.

Updates

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.

sarah/acts_as_mailchimp