Merge 689bd4b into 88da3ab

README.rst

@@ -7,6 +7,7 @@
 .. _Sign up: https://app.sparkpost.com/sign-up?src=Dev-Website&sfdcid=70160000000pqBb
 .. _Developer Hub: https://developers.sparkpost.com
 
+===========================
 SparkPost Python API client
 ===========================
 
@@ -30,7 +31,7 @@ The super-mega-official Python package for using the SparkPost API.
 
 
 Installation
-------------
+============
 
 Install from PyPI using `pip`_:
 
@@ -40,13 +41,11 @@ Install from PyPI using `pip`_:
 
 .. _pip: http://www.pip-installer.org/en/latest/
 
-.. _pip: http://www.pip-installer.org/en/latest/
-
 
-Get a key
----------
+Initialization
+==============
 
-Go to `API & SMTP`_ in the SparkPost app and create an API key. We recommend using the ``SPARKPOST_API_KEY`` environment variable:
+Go to `API Keys`_ in the SparkPost app and create an API key. We recommend using the ``SPARKPOST_API_KEY`` environment variable:
 
 .. code-block:: python
 
@@ -60,11 +59,11 @@ Alternatively, you can pass the API key to the SparkPost class:
     from sparkpost import SparkPost
     sp = SparkPost('YOUR API KEY')
 
-.. _API & SMTP: https://app.sparkpost.com/#/configuration/credentials
+.. _API Keys: https://app.sparkpost.com/account/credentials
 
 
 Send a message
---------------
+==============
 
 Here at SparkPost, our messages are known as transmissions. Let's use the underlying `transmissions API`_ to send a friendly test message:
 
@@ -74,37 +73,126 @@ Here at SparkPost, our messages are known as transmissions. Let's use the underl
 
     sp = SparkPost()
 
-    response = sp.transmissions.send(
-        use_sandbox=True,
-        recipients=['someone@somedomain.com'],
-        html='<p>Hello world</p>',
-        from_email='test@sparkpostbox.com',
-        subject='Hello from python-sparkpost'
-    )
+    response = sp.transmissions.post({
+      'options': {
+        'sandbox': True,
+        'open_tracking': True,
+        'click_tracking': True,
+      },
+      'recipients': ['someone@somedomain.com'],
+      'content': {
+        'from': 'test@sparkpostbox.com',
+        'subject': 'Hello from python-sparkpost',
+        'text': 'Hello world!',
+        'html': '<p>Hello world!</p>',
+      },
+    })
 
     print(response)
     # outputs {u'total_accepted_recipients': 1, u'id': u'47960765679942446', u'total_rejected_recipients': 0}
 
-.. _transmissions API: https://www.sparkpost.com/api#/reference/transmissions
+.. _transmissions API: https://developers.sparkpost.com/api/transmissions.html
 
-Django Integration
-------------------
-The SparkPost python library comes with an email backend for Django. Put the following configuration in `settings.py` file.
+Custom wrappers
+===============
+
+We use custom wrappers to add some syntactic sugar on top of our API. For example the ``sp.transmissions`` wrapper adds a simple way to define ``cc``, ``bcc``, and ``attachments`` for a transmission. These wrappers use the library's `base resource`_. 
+
+.. _base resource: https://github.com/SparkPost/python-sparkpost/blob/master/sparkpost/base.py
+
+Using the base resource
+=======================
+
+The base resource can be used to access any of our endpoints through a common interface. Examples for each type of HTTP method follow.
+
+Get a list of all webhooks (GET):
+
+.. code-block:: python
+
+    from sparkpost import SparkPost
+
+    sp = SparkPost()
+
+    response = sp.get(uri='webhooks')
+
+Get a specific webhook (GET):
+
+.. code-block:: python
+
+    from sparkpost import SparkPost
+
+    sp = SparkPost()
+
+    # or get a specific webhook
+    response = sp.get(
+        uri='webhooks/12affc24-f183-11e3-9234-3c15c2c818c2'
+    )
+
+Create a webhook (POST):
+
+.. code-block:: python
+
+    from sparkpost import SparkPost
+
+    sp = SparkPost()
+
+    response = sp.post(
+        uri='webhooks',
+        payload={
+          'name': 'Example webhook',
+          'target': 'http://client.example.com/example-webhook',
+          'events': [
+            'delivery',
+            'injection',
+            'open',
+            'click'
+          ]
+        }
+    )
+
+Update a webhook (PUT):
 
 .. code-block:: python
 
-    SPARKPOST_API_KEY = 'API_KEY'
-    EMAIL_BACKEND = 'sparkpost.django.email_backend.SparkPostEmailBackend'
+    from sparkpost import SparkPost
+
+    sp = SparkPost()
 
-Replace *API_KEY* with an actual API key that you've generated in `Get a Key`_ section. Check out the `full documentation`_ on the Django email backend.
+    response = sp.put(
+        uri='webhooks/12affc24-f183-11e3-9234-3c15c2c818c2',
+        payload={
+          'target': 'http://client.example.com/different-endpoint'
+        }
+    )
 
-.. _full documentation: https://python-sparkpost.readthedocs.io/en/latest/django/backend.html
+Delete a webhook (DELETE):
+
+.. code-block:: python
+
+    from sparkpost import SparkPost
+
+    sp = SparkPost()
+
+    response = sp.delete(
+        uri='webhooks/12affc24-f183-11e3-9234-3c15c2c818c2'
+    )
+
+
+Integrations
+============
+
+Django Integration
+------------------
+
+We recommend the `django-anymail`_ package for using SparkPost with Django.
+
+.. _django-anymail: https://github.com/anymail/django-anymail
 
 Using with Google Cloud
 -----------------------
 There are a few simple modifications necessary to enable the use of the underlying ``requests`` library that python-sparkpost uses. First, add the ``requests`` and ``requests-toolbelt`` to your project's ``requirements.txt``:
 
-.. code-block::
+.. code-block:: text
 
     requests
     requests-toolbelt
@@ -115,13 +203,15 @@ Then create or update your ``appengine_config.py`` file to include the following
 
     import requests
     import requests_toolbelt.adapters.appengine
-    
+
     requests_toolbelt.adapters.appengine.monkeypatch()
 
-Then deploy your app and you should be able to send using python-sparkpost on Google Cloud.
+Then deploy your app and you should be able to send using python-sparkpost on Google Cloud. We've also set up `some sample applications`_ on Github as a reference.
+
+.. _some sample applications: https://github.com/search?q=org%3ASparkPost+google
 
 Documentation
--------------
+=============
 
 * Documentation for `python-sparkpost`_
 * `SparkPost API Reference`_
@@ -131,7 +221,7 @@ Documentation
 
 
 Contribute
-----------
+==========
 
 #. Check for open issues or open a fresh issue to start a discussion around a feature idea or a bug.
 #. Fork `the repository`_ on GitHub and make your changes in a branch on your fork