Workarea Mail Chimp
================================================================================

MailChimp plugin for the Worakrea e-commerce platform

This plugin creates a basic integration between the WebLinc platform and
MailChimp's v3 API

It requires a mailchimp access token which can be generated by following
MailChimp's OAuth2 Flow here: <http://developer.mailchimp.com/documentation/mailchimp/guides/how-to-use-oauth2/>

Scope and Dependencies
--------------------------------------------------------------------------------

This plugin currently wraps functionality for subscribing and unsubscribing users
by email, as well as retrieving interest groups (or categories) for users and lists

It is dependant on the [gibbon rubygem](https://github.com/amro/gibbon) which
provides a basic wrapper for the MailChimp v3 API.

Configuration
--------------------------------------------------------------------------------

This plugin requires gateway configuration in order to function.

In your secrets file:

    mail_chimp:
      :api_key: APIKEY
      :default_list_id: LIST_ID
      :list_preferences_id: LIST_PREFERENCES_ID

### To find your default list ID, in the mailchimp admin:

1. Go to the list you wish to use
2. Click the settings dropdown menu
3. Choose the 'List name and defaults' menu item
4. You will find the List ID on this page, at the time of writing it is displayed
    at the top left of the page.

### To find your list preferences ID via the API playground:

1. Visit [API playground](https://us16.api.mailchimp.com/playground/)
2. Enter your API key
3. Click on the 'Lists' Link
4. Find the subresources dropdown for your default list
5. Choose 'interest-categories' from the subresources dropdown
6. Click the name of your interest group
7. Use the ID field shown in the details section, the 'list_id' field should
    correspond with your default_list_id

Testing & Maintenance
--------------------------------------------------------------------------------

Ensure that the gateway credentials within application secrets are set in
`spec/dummy/config/secrets.yml` for test mode

To get specs to pass, you will need to configure a MailChimp account with the
following data

* A group/category with the same information as what is configured in
    `HelperMethods#email_all_interests_hash` in `spec/fixtures/helper_methods.rb`

* A user that was unsubscribed with the following email: `test-unsubscribed@weblinc.com`

* A subscribed user with the following email: `mdalton-simonpearce@weblinc.com`

The specs use VCR cassettes to record http requests, so maintainers will need to
    flush the cassettes when modifying the requests.

Getting Started
--------------------------------------------------------------------------------

This gem contains a rails engine that must be mounted onto a host Rails application.

You must have access to a WebLinc gems server to use this gem. Add your gems
server credentials to Bundler:

    bundle config gems.weblinc.com my_username:my_password

Or set the appropriate environment variable in a shell startup file:

    export BUNDLE_GEMS__WEBLINC__COM='my_username:my_password'

Then add the gem to your application's Gemfile specifying the source:

    # ...
    gem 'workarea-mail_chimp', source: 'https://gems.weblinc.com'
    # ...

Or use a source block:

    # ...
    source 'https://gems.weblinc.com' do
      gem 'workarea-mail_chimp'
    end
    # ...

Update your application's bundle.

    cd path/to/application
    bundle

WebLinc Platform Documentation
--------------------------------------------------------------------------------

See [http://developer.weblinc.com](http://developer.weblinc.com) for Workarea
platform documentation.

Copyright & Licensing
--------------------------------------------------------------------------------

Copyright WebLinc 2015. All rights reserved.

For licensing, contact sales@weblinc.com.