Package: django-chimpusers
django-chimpusers=================Integrates users from Django's authentication system `django.contrib.auth` witha [MailChimp][1] email marketing list. Provides a model to store opt-in dataand 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 caninstall 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-chimpusersFor the latest development version, install from the git repository.git clone git@github.com:Quixotix/django-chimpusers.gitsetup.py install django-chimpusersThen, add `chimpusers` to your installed apps and sync the database:./manage.py syncdbSettings--------* `MAILCHIMP_API_KEY` - [required] Your MailChimp API key.* `MAILCHIMP_LIST_ID` - [required] The list ID of the MailChimp list you want to integratewith.* `MAILCHIMP_TEST_IP` - [optional] A __public__ IP address to use with the test cases. Thismust be a public IP for the tests to pass.How it Works------------### The UserSubscription ModelA `UserSubscription` model is created each time a `User` is created. This modelsimply provides some convenience methods that wrap MailSnake calls to theMailChimp 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 newmembers or in a specific view for subscribing to your email list. (You makesure your users are opting in right? They should be physically checking a checkbox, clicking a big "subscribe" button, etc. Don't spam folks, they don't likeit)__UserSubscription.subscribe()__The `UserSubscription.subscribe()` calls [listSubscribe][6], automaticallyadding the list ID, the user's email, the user's first name, and the user'slast name. All other parameters defined for [listSubscribe][6] can be passedto `UserSubscription.subscribe()` as keyword arguments (again, it just wrapsMailSnake).from chimpusers.models import UserSubscription# ...subscription = UserSubscription.objects.get(user=request.user)subscription.subscribe() # double_optin is True by defaultIf the MailChimp API returns an error (say the email is already subscribed), youcan catch the `MailChimpError` eception.from chimpusers.models import UserSubscriptionfrom chimpusers.exceptions import MailChimpError# ...subscription = UserSubscription.objects.get(user=request.user)try:subscription.subscribe() # double_optin is True by defaultexcept MailChimpError as e:# Handle exception. Message will be that returned by MailChimp.passWhen you subscribe a user you should save the user's IP address and a timestampas opt-in "proof".from datetime import datetimefrom 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 proxyoptin_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()` justwraps 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], automaticallyadding the list ID, the user's email, the user's first name, and the user'slast name. All other parameters defined for [listMemberUpdate][7] can be passedto `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], automaticallyadding the list ID and the user's email. All other parameters defined for[listUnsubscribe][8] can be passed to `UserSubscription.unsubscribe()` askeyword 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 modelfields with the MailChimp API. Since the user or an administrator can manipulatesubscriptions 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 FactoryOne of the great features of MailChimp is to segregate your list into variousinterest [groups][3]. This allows you to maintain one list for your website'susers 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, andgroups to allow their customers to recieve a monthly newsletter, another groupfor new product announcements, and another group for holiday promotions.The `groups_form_factory()` function dynamically generates a form for opting inand out of your list's groups. This could be used in a view allowing existingsubscribers to modify their group preferences or combined with a registrationform to allow new subscribers to opt-in to specific groups at sign up.from chimpusers.models import UserSubscriptionfrom chimpusers.forms import groups_form_factoryfrom 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 groupssubscription.update(merge_vars=merge)else:# subscribeoptin_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_ipmerge['OPTIN_TIME'] = optin_timesubscription.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