-
Notifications
You must be signed in to change notification settings - Fork 67
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Update docs for 2.x #152
Update docs for 2.x #152
Changes from 9 commits
070f10e
6e99a71
cd7e97d
e7c0004
dbe42d6
d2d909d
3b92911
2a5d771
1f9021f
61ba6d1
d9d7e23
689bd4b
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -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 | ||
=============== | ||
|
||
The ``sp.transmissions`` object is a wrapper around the library's `base resource`_. We create wrappers to add some syntactic sugar on top of our API. For example, adding ``cc`` and ``bcc`` to a transmission. | ||
|
||
.. _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 | ||
|
||
SPARKPOST_API_KEY = 'API_KEY' | ||
EMAIL_BACKEND = 'sparkpost.django.email_backend.SparkPostEmailBackend' | ||
from sparkpost import SparkPost | ||
|
||
sp = SparkPost() | ||
|
||
response = sp.get(uri='webhooks') | ||
|
||
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. | ||
Get a specific webhook (GET): | ||
|
||
.. _full documentation: https://python-sparkpost.readthedocs.io/en/latest/django/backend.html | ||
.. 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 | ||
|
||
from sparkpost import SparkPost | ||
|
||
sp = SparkPost() | ||
|
||
response = sp.put( | ||
uri='webhooks/12affc24-f183-11e3-9234-3c15c2c818c2', | ||
payload={ | ||
'target': 'http://client.example.com/different-endpoint' | ||
} | ||
) | ||
|
||
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 was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Is it worth linking to our 2 Google App Engine python samples? (...and we should likely update them once python-sparkpsot 2.0 drops...) There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. added |
||
----------------------- | ||
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,13 @@ 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. | ||
|
||
Documentation | ||
------------- | ||
============= | ||
|
||
* Documentation for `python-sparkpost`_ | ||
* `SparkPost API Reference`_ | ||
|
@@ -131,7 +219,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 | ||
|
This file was deleted.
This file was deleted.
This file was deleted.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Tiny nit: There's a sentence fragment in there.
For example, adding cc and bcc to a transmission
.How about:
For example, the wrapper makes it easy to add CC and BCC recipients to a transmission
.