SubscribedTo

Abstraction layer for managing mailing list subscription information for your user model. It makes the basic mailing list management tasks super simple.

The gem creates callbacks on your model for after_create and after_update.

The after_create callback registers the user for the mailing list if subscribed_to_list is true (ie: the user chooses checks the “Join the mailing list” box on the registration form).

The after_update callback will update the user subscription or member details. It will either:

Unsubscribe the user from the mailing list if they have so requested
Subscribe the user to the list if they weren’t already subscribed
Update the user’s member subscription details on the mailing list for any specified merge_vars when they change
Do nothing if neither the subscription status nor the attributes specified in the merge_vars hash change

Requirements

Rails 3.x

Supported Services

MailChimp

via the Hominid gem - github.com/terra-firma/hominid

API v1.3 - apidocs.mailchimp.com/1.3

listSubscribe
listUnsubscribe
listUpdateMember

Adds support for MailChimp webhooks

Constant Contact

Planned

Installation

Add the gem to your Gemfile

gem "subscribed_to"

Install the gem using bundler

bundle install

Run the generator. You must specify the name of your user model. Other options:

--skip-migration: Do not generate the migration file to add the required column
--service=SERVICE: Specify which mailing list service you subscribe to (currently only supports “mail_chimp”)

rails generate subscribed_to:install MODEL

If you run the generator with --skip-migration, then you must be sure to to include the subscribed_to_list column in some other migration.

t.boolean :subscribed_to_list, :default => false

Be sure to run the migration before you continue.

Initializer Configuration

After the initializer has been generated, you must set your mail service configuration options. The initializer is located at: config/initializers/subscribe_to.rb

Mail Chimp

Set your API key

mail_chimp_config.api_key = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX-us1"

Set up your mailing lists to subscribe users to. List names can be any valid symbol.

:id: id of list - get this from the “Settings” page of your list
:merge_vars: hash of merge vars on list. The key is a string which corresponds to a merge var on your mailing list. The value is a symbol corresponding to the attribute/method on the user model related to the specified merge var. It MUST at least include “EMAIL” (do not use “MERGE0”).

mail_chimp_config.lists = {
  :mailing_list => {
    :id => "xxxxxxxx",
    :merge_vars => {"FNAME" => :first_name, "LNAME" => :last_name, "EMAIL" => :email}}}

Set your secret key for the webhook URL.

Keep this key a secret. It’s the only line of defense of preventing unwanted POST requests to the URL.

mail_chimp_config.secret_key = "my_secret_key_that_i_will_change"

Webhooks

The gem sets up support for MailChimp webhooks. Read more here: apidocs.mailchimp.com/webhooks/

First, you need to setup webhooks in your MailChimp account.

1) On the list tools page, click the “WebHooks” link.

2) Enter the webhook URL as:

http://mywebapp.com/subscribed_to/mail_chimp?key=<secret_key_defined_in_config>

3) Enable updates for events:

Subscribes
Unsubscribes
Profile Updates
Email Changed

4) Send updates when a change was made by…

A subscriber
Account admin
Via the API

5) Click “Update”

User Model Configuration

You must enable SubscribedTo in your user model with subscribed_to.

The only paramter it takes is a symbol which corresponds to a list in the mail_chimp_config.lists hash.

subscribed_to :mailing_list

You may also need to specify subscribed_to_list as an accessible attribute.

attr_accessible :subscribed_to_list

View Configuration

To get things working with the view, just include a checkbox input on your user registration/edit forms.

= f.check_box :subscribed_to_list
= f.label :subscribed_to_list, "Join the mailing list"

Contributing to subscribed_to

Check out the latest master to make sure the feature hasn’t been implemented or the bug hasn’t been fixed yet
Check out the issue tracker to make sure someone already hasn’t requested it and/or contributed it
Fork the project
Start a feature/bugfix branch
Commit and push until you are happy with your contribution
Make sure to add tests for it. This is important so I don’t break it in a future version unintentionally.
Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.