Merge pull request #48 from aydrian/ISSUE-12

Added Recipient Lists resource lib

docs/api/recipient_lists.rst

@@ -0,0 +1,7 @@
+.. module:: sparkpost.recipient_lists
+
+:mod:`sparkpost.recipient_lists`
+================================
+
+.. autoclass:: RecipientLists
+   :members:

docs/api/transmissions.rst

@@ -1,7 +1,7 @@
-.. module:: sparkpost.transmission
+.. module:: sparkpost.transmissions
 
-:mod:`sparkpost.transmission`
-=============================
+:mod:`sparkpost.transmissions`
+==============================
 
-.. autoclass:: Transmission
+.. autoclass:: Transmissions
    :members:

docs/resources/recipient_lists.rst

@@ -0,0 +1,83 @@
+Recipient Lists
+===============
+
+Let's use the underlying `recipient_lists API`_ to create a recipient list:
+
+.. code-block:: python
+
+    from sparkpost import SparkPost
+
+    sp = SparkPost()
+
+    response = sp.recipient_lists.create(
+        id='UNIQUE_TEST_ID',
+        name='Test Recipient list',
+        recipients=[
+            {
+                'address': {
+                    'email': 'test1@test.com'
+                }
+            },
+            {
+                'address': {
+                    'email': 'test2@test.com'
+                }
+            },
+            {
+                'address': {
+                    'email': 'test3@test.com'
+                }
+            }
+        ]
+    )
+
+    print response
+    # outputs {u'total_accepted_recipients': 3, u'id': u'UNIQUE_TEST_ID', u'total_rejected_recipients': 0, u'name':'Test Recipient list'}
+
+.. _recipient_lists API: https://www.sparkpost.com/api#/reference/recipient-lists
+
+
+Retrieve a recipient list
+-------------------------
+
+.. code-block:: python
+
+    from sparkpost import SparkPost
+
+    sp = SparkPost()
+
+    sp.recipient_lists.get('my-list-id')
+
+
+List all recipient lists
+------------------------
+
+.. code-block:: python
+
+    from sparkpost import SparkPost
+
+    sp = SparkPost()
+
+    sp.recipient_lists.list()
+
+
+API reference
+-------------
+
+:doc:`/api/recipient_lists`
+
+
+Further examples
+----------------
+
+See the `python-sparkpost recipient_lists examples`_.
+
+.. _python-sparkpost recipient_lists examples: https://github.com/SparkPost/python-sparkpost/tree/master/examples/recipient_lists
+
+
+Additional documentation
+------------------------
+
+See the `SparkPost Recipient Lists API Reference`_.
+
+.. _SparkPost Recipient Lists API Reference: https://www.sparkpost.com/api#/reference/recipient_lists

examples/recipient_lists/create_recipient_list.py

@@ -0,0 +1,25 @@
+from sparkpost import SparkPost
+
+sp = SparkPost('YOUR API KEY')
+response = sp.recipient_lists.create(
+    id='UNIQUE_TEST_ID',
+    name='Test Recipient list',
+    recipients=[
+        {
+            'address': {
+                'email': 'test1@test.com'
+            }
+        },
+        {
+            'address': {
+                'email': 'test2@test.com'
+            }
+        },
+        {
+            'address': {
+                'email': 'test3@test.com'
+            }
+        }
+    ]
+)
+print response

examples/recipient_lists/delete_recipient_list.py

@@ -0,0 +1,5 @@
+from sparkpost import SparkPost
+
+sp = SparkPost('YOUR API KEY')
+result = sp.recipient_lists.delete('list_id')
+print result

examples/recipient_lists/get_recipient_list.py

@@ -0,0 +1,5 @@
+from sparkpost import SparkPost
+
+sp = SparkPost('YOUR API KEY')
+recipient_list = sp.recipient_lists.get('list_id')
+print recipient_list

examples/recipient_lists/get_recipient_list_with_recipients.py

@@ -0,0 +1,5 @@
+from sparkpost import SparkPost
+
+sp = SparkPost('YOUR API KEY')
+recipient_list = sp.recipient_lists.get('list_id', True)
+print recipient_list

examples/recipient_lists/list_recipient_lists.py

@@ -0,0 +1,5 @@
+from sparkpost import SparkPost
+
+sp = SparkPost('YOUR API KEY')
+recipient_lists = sp.recipient_lists.list()
+print recipient_lists

examples/recipient_lists/update_recipient_list.py

@@ -0,0 +1,25 @@
+from sparkpost import SparkPost
+
+sp = SparkPost('YOUR API KEY')
+response = sp.recipient_lists.update(
+    'EXISTING_TEST_ID',
+    name='Test Recipient list',
+    recipients=[
+        {
+            'address': {
+                'email': 'test1@test.com'
+            }
+        },
+        {
+            'address': {
+                'email': 'test2@test.com'
+            }
+        },
+        {
+            'address': {
+                'email': 'test3@test.com'
+            }
+        }
+    ]
+)
+print response

examples/templates/delete_template.py

@@ -1,5 +1,5 @@
 from sparkpost import SparkPost
 
 sp = SparkPost('YOUR API KEY')
-template = sp.transmission.delete('template_id')
-print template
+result = sp.templates.delete('template_id')
+print result

examples/templates/get_template.py

@@ -1,5 +1,5 @@
 from sparkpost import SparkPost
 
 sp = SparkPost('YOUR API KEY')
-template = sp.transmission.get('template_id')
+template = sp.templates.get('template_id')
 print template

examples/templates/preview_draft_template.py

@@ -5,5 +5,5 @@
     'first_name': 'John',
     'last_name': 'Doe'
 }
-template = sp.transmission.preview('template_id', sub_data, True)
+template = sp.templates.preview('template_id', sub_data, True)
 print template

examples/templates/preview_template.py

@@ -5,5 +5,5 @@
     'first_name': 'John',
     'last_name': 'Doe'
 }
-template = sp.transmission.preview('template_id', sub_data)
+template = sp.templates.preview('template_id', sub_data)
 print template

sparkpost/__init__.py

@@ -2,6 +2,7 @@
 
 from .exceptions import SparkPostException
 from .metrics import Metrics
+from .recipient_lists import RecipientLists
 from .templates import Templates
 from .transmissions import Transmissions
 
@@ -27,6 +28,7 @@ def __init__(self, api_key=None, base_uri='https://api.sparkpost.com',
         self.api_key = api_key
 
         self.metrics = Metrics(self.base_uri, self.api_key)
+        self.recipient_lists = RecipientLists(self.base_uri, self.api_key)
         self.templates = Templates(self.base_uri, self.api_key)
         self.transmissions = Transmissions(self.base_uri, self.api_key)
         # Keeping self.transmission for backwards compatibility.

sparkpost/recipient_lists.py

@@ -0,0 +1,105 @@
+import json
+
+from .base import Resource
+
+
+class RecipientLists(Resource):
+    """
+    RecipientLists class used to create, update, delete, list and get recipient
+    lists. For detailed request and response formats, see the `Recipient Lists
+    API documentation
+    <https://www.sparkpost.com/api#/reference/recipient-lists>`_.
+    """
+
+    key = 'recipient-lists'
+
+    def _translate_keys(self, **kwargs):
+        model = {}
+
+        if 'id' in kwargs:
+            model['id'] = kwargs.get('id')
+        model['name'] = kwargs.get('name')
+        model['description'] = kwargs.get('description')
+        model['attributes'] = kwargs.get('attributes')
+        model['recipients'] = kwargs.get('recipients')
+
+        return model
+
+    def create(self, **kwargs):
+        """
+        Create a recipient list based on the supplied parameters
+
+        :param str id: ID used to reference the recipient list
+        :param str name: Editable display name
+        :param str description: Detailed description of the recipient list
+        :param dict attributes: Arbitrary metadata related to the list
+        :param list recipients: Array of recipient dicts
+
+        :returns: a ``dict`` with the ID, name, and number of accepted
+            and rejected recipients
+        :raises: :exc:`SparkPostAPIException` if API call fails
+        """
+        payload = self._translate_keys(**kwargs)
+        results = self.request('POST', self.uri, data=json.dumps(payload))
+        return results
+
+    def update(self, list_id, **kwargs):
+        """
+        Update a recipient list by ID based on the supplied parameters
+
+        :param str list_id: ID of the recipient list you want to update
+        :param str name: Editable display name
+        :param str description: Detailed description of the recipient list
+        :param dict attributes: Arbitrary metadata related to the list
+        :param list recipients: Array of recipient dicts
+
+        :returns: a ``dict`` with the ID, name, and number of accepted
+            and rejected recipients
+        :raises: :exc:`SparkPostAPIException` if API call fails
+        """
+        uri = "%s/%s" % (self.uri, list_id)
+        payload = self._translate_keys(**kwargs)
+        results = self.request('PUT', uri, data=json.dumps(payload))
+        return results
+
+    def delete(self, list_id):
+        """
+        Delete a recipient list by ID
+
+        :param str list_id: ID of the recipient list you want to delete
+
+        :returns: empty ``dict``
+        :raises: :exc:`SparkPostAPIException` if recipient list is not found
+            or if recipient list is in use
+        """
+        uri = "%s/%s" % (self.uri, list_id)
+        results = self.request('DELETE', uri)
+        return results
+
+    def get(self, list_id, show_recipients=None):
+        """
+        Get a recipient list by ID
+
+        :param str list_id: ID of the recipient list you want to retrieve
+        :param bool show_recipients: If True, returns attributes for
+            all recipients
+
+        :returns: the requested recipient list if found
+        :raises: :exc:`SparkPostAPIException` if recipient list is not found
+        """
+        uri = "%s/%s" % (self.uri, list_id)
+        params = {}
+        if show_recipients is not None:
+            params['show_recipients'] = str(show_recipients).lower()
+        results = self.request('GET', uri, params=params)
+        return results
+
+    def list(self):
+        """
+        Get a list of your recipient lists
+
+        :returns: list of recipient lists
+        :raises: :exc:`SparkPostAPIException` if API call fails
+        """
+        results = self.request('GET', self.uri)
+        return results

sparkpost/templates.py

@@ -118,7 +118,7 @@ def delete(self, template_id):
 
         :returns: TODO
         :raises: :exc:`SparkPostAPIException` if template is not found or if
-        template is in use
+            template is in use
         """
         uri = "%s/%s" % (self.uri, template_id)
         results = self.request('DELETE', uri)