Metadata-Version: 1.1
Name: django-chimpusers
Version: 0.1.5
Summary: Integrate Django users with a MailChimp mailing list.
Home-page: https://github.com/Quixotix/django-chimpusers
Author: Micah Carrick
Author-email: micah@quixotix.com
License: BSD
Description: django-chimpusers
        =================
        
        Integrates users from Django's authentication system `django.contrib.auth` with
        a [MailChimp][1] email marketing list. Provides a model to store opt-in data 
        and a form factory to allow users to edit their [interest groups][3].
        
        
        Requirements
        ------------
        
        * [MailSnake][10], a Python wrapper for the [MailChimp v1.3 API][2]. You can
          install MailSnake using `easy_install` or `pip`:
        
            pip install mailsnake
        
        * The API key for your MailChimp account. [Where can I find my API key?][4]
        * The ID of the list you want to integrate with. [How can I find my List ID?][5]
        
        
        Installation
        ------------
        
        For the latest stable version, install using `easy_install` or `pip`:
        
            pip install django-chimpusers
        
        For the latest development version, install from the git repository.
        
            git clone git@github.com:Quixotix/django-chimpusers.git
            setup.py install django-chimpusers
        
        Then, add `chimpusers` to your installed apps and sync the database:
        
            ./manage.py syncdb
        
        
        Settings
        --------
        
        * `MAILCHIMP_API_KEY` - [required] Your MailChimp API key. 
        * `MAILCHIMP_LIST_ID` - [required] The list ID of the MailChimp list you want to integrate
          with.
        * `MAILCHIMP_TEST_IP` - [optional] A __public__ IP address to use with the test cases. This 
          must be a public IP for the tests to pass.
        
        
        How it Works
        ------------
        
        ### The UserSubscription Model
        
        A `UserSubscription` model is created each time a `User` is created. This model 
        simply provides some convenience methods that wrap MailSnake calls to the 
        MailChimp API. It also stores the user's subscription status, opt-in IP addresss, 
        and opt-in date.
        
        You would typically use `UserSubscription` when you register or activate new
        members or in a specific view for subscribing to your email list. (You make
        sure your users are opting in right? They should be physically checking a check 
        box, clicking a big "subscribe" button, etc. Don't spam folks, they don't like
        it)
        
        __UserSubscription.subscribe()__
        
        The `UserSubscription.subscribe()` calls [listSubscribe][6], automatically 
        adding the list ID, the user's email, the user's first name, and the user's 
        last name. All other parameters defined for [listSubscribe][6] can be passed 
        to `UserSubscription.subscribe()` as keyword arguments (again, it just wraps
        MailSnake).
        
            from chimpusers.models import UserSubscription
            
            # ...
            
            subscription = UserSubscription.objects.get(user=request.user)
            subscription.subscribe() # double_optin is True by default
        
        If the MailChimp API returns an error (say the email is already subscribed), you
        can catch the `MailChimpError` eception.
        
            from chimpusers.models import UserSubscription
            from chimpusers.exceptions import MailChimpError
            
            # ...
            
            subscription = UserSubscription.objects.get(user=request.user)
            try:
                subscription.subscribe() # double_optin is True by default
            except MailChimpError as e:
                # Handle exception. Message will be that returned by MailChimp.
                pass
        
        When you subscribe a user you should save the user's IP address and a timestamp 
        as opt-in "proof".
        
            from datetime import datetime
            from chimpusers.models import UserSubscription
            
            # ...
            
            subscription = UserSubscription.objects.get(user=request.user)
            optin_time = datetime.now().strftime('%Y-%m-%d %H:%M:%S')
            if 'HTTP_X_FORWARDED_FOR' in request.META: # IP forwarded from proxy
                optin_ip = request.META['HTTP_X_FORWARDED_FOR']
            else:
                optin_ip = request.META['REMOTE_ADDR']
            merge_vars = {'OPTIN_IP': optin_ip, 'OPTIN_TIME': optin_time}
            
            subscription.subscribe(merge_vars=merge_vars)
        
        And just to drive home the point that the `UserSubscription.subscribe()` just
        wraps a MailSnake call to [listSubscribe][6]...
        
            from chimpusers.models import UserSubscription
            
            # ...
            
            subscription = UserSubscription.objects.get(user=request.user)
            subscription.subscribe(email_type="text", 
                                   double_optin=False, 
                                   update_existing=True, 
                                   replace_interests=False, 
                                   send_welcome=True)
        
        
        __UserSubscription.update()__
        
        The `UserSubscription.update()` calls [listMemberUpdate][7], automatically 
        adding the list ID, the user's email, the user's first name, and the user's 
        last name. All other parameters defined for [listMemberUpdate][7] can be passed 
        to `UserSubscription.update()` as keyword arguments.
        
            from chimpusers.models import UserSubscription
            
            # ...
            
            subscription = UserSubscription.objects.get(user=request.user)
            merge_vars = {"GROUPINGS": [{"name":"Interest Groups", 
                                         "groups":"Monthly Newsletter,New Products"}]}
            subscription.update(merge_vars=merge_vars)
        
        
        __UserSubscription.unsubscribe()__
        
        The `UserSubscription.unsubscribe()` calls [listUnsubscribe][8], automatically 
        adding the list ID and the user's email. All other parameters defined for 
        [listUnsubscribe][8] can be passed to `UserSubscription.unsubscribe()` as 
        keyword arguments.
        
            from chimpusers.models import UserSubscription
            
            # ...
            
            subscription = UserSubscription.objects.get(user=request.user)
            subscription.unsubscribe(send_goodbye=False, send_notify=True)
        
        
        __UserSubscription.sync()__
            
        The `UserSubscription` model provides the `sync` method to synchronize the model
        fields with the MailChimp API. Since the user or an administrator can manipulate
        subscriptions from the MailChimp website and you _may_ not have any [webhooks][9]
        setup yet, syncing the `UserSubscription` can come in handy.
        
            from chimpusers.models import UserSubscription
            
            # ...
            
            subscription = UserSubscription.objects.get(user=request.user)
            subscription.sync()
            # the following fields are now in sync with MailChimp
            # subscription.status
            # subscription.optin_ip
            # subscription.optin_time
        
        
        ### The groups_form_factory Form Factory
        
        One of the great features of MailChimp is to segregate your list into various
        interest [groups][3]. This allows you to maintain one list for your website's 
        users and allow them to sign up for one or more groups. 
        
        For example, an e-commerce website may have a list of all their customers, and
        groups to allow their customers to recieve a monthly newsletter, another group
        for new product announcements, and another group for holiday promotions.
        
        The `groups_form_factory()` function dynamically generates a form for opting in
        and out of your list's groups. This could be used in a view allowing existing
        subscribers to modify their group preferences or combined with a registration
        form to allow new subscribers to opt-in to specific groups at sign up.
        
            from chimpusers.models import UserSubscription
            from chimpusers.forms import groups_form_factory
            from datetime import datetime
            
            # ...
            
            subscription = UserSubscription.objects.get(user=request.user)
            GroupsForm = groups_form_factory(request.user.email)
            
            if request.method == 'POST':
                form = GroupsForm(request.post)
                if form.is_valid():
                    merge_vars = {'GROUPINGS': [form.merge_var]}
                    if subscription.is_subscribed():
                        # update user's groups
                        subscription.update(merge_vars=merge)
                    else:
                        # subscribe
                        optin_time = datetime.now().strftime('%Y-%m-%d %H:%M:%S')
                        if 'HTTP_X_FORWARDED_FOR' in request.META:
                            optin_ip = request.META['HTTP_X_FORWARDED_FOR']
                        else:
                            optin_ip = request.META['REMOTE_ADDR']
                        merge['OPTIN_IP'] = optin_ip
                        merge['OPTIN_TIME'] = optin_time
                        subscription.subscribe(merge_vars=merge)
            else:
                form = GroupsForm()
            
            # ...
            
        
        [1]: http://mailchimp.com
        [2]: http://apidocs.mailchimp.com/api/1.3/
        [3]: http://mailchimp.com/features/groups/
        [4]: http://kb.mailchimp.com/article/where-can-i-find-my-api-key/
        [5]: http://kb.mailchimp.com/article/how-can-i-find-my-list-id/
        [6]: http://apidocs.mailchimp.com/api/1.3/listsubscribe.func.php
        [7]: http://apidocs.mailchimp.com/api/1.3/listupdatemember.func.php
        [8]: http://apidocs.mailchimp.com/api/1.3/listunsubscribe.func.php
        [9]: http://apidocs.mailchimp.com/webhooks/
        [10]: https://github.com/leftium/mailsnake
        
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: BSD License
