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

• Rails 3.x

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

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 and mail_chimp_id columns in some other migration.

t.boolean :subscribed_to_list, :default => false
t.integer :mail_chimp_id

Be sure to run the migration before you continue.

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

Activate the gem. Can be disabled for development, staging, etc environtments. Activated only in production environment by default.

config.active = true

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"

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”

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

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"

• 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.

Copyright © 2011 Eric Salczynski. See LICENSE.txt for further details.