0.0
No commit activity in last 3 years
No release in over 3 years
Abstract layer for managing mailing list subscriptions
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Dependencies

Development

Runtime

 Project Readme

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

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¶ ↑

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"

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.

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