Sign up for a SparkPost account and visit our Developer Hub for even more content.

The super-mega-official Python package for using the SparkPost API.

Install from PyPI using pip:

$ pip install sparkpost

Go to API Keys in the SparkPost app and create an API key. We recommend using the SPARKPOST_API_KEY environment variable:

from sparkpost import SparkPost
sp = SparkPost() # uses environment variable

Alternatively, you can pass the API key to the SparkPost class:

from sparkpost import SparkPost
sp = SparkPost('YOUR API KEY')

Here at SparkPost, our messages are known as transmissions. Let's use the underlying transmissions API to send a friendly test message:

from sparkpost import SparkPost

sp = 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}

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.

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):

from sparkpost import SparkPost

sp = SparkPost()

response = sp.get(uri='webhooks')

Get a specific webhook (GET):

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):

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):

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):

from sparkpost import SparkPost

sp = SparkPost()

response = sp.delete(
    uri='webhooks/12affc24-f183-11e3-9234-3c15c2c818c2'
)

We recommend the django-anymail package for using SparkPost with Django.

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:

requests
requests-toolbelt

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. We've also set up some sample applications on Github as a reference.

• Documentation for python-sparkpost
• SparkPost API Reference

1. Check for open issues or open a fresh issue to start a discussion around a feature idea or a bug.
2. Fork the repository on GitHub and make your changes in a branch on your fork
3. Write a test which shows that the bug was fixed or that the feature works as expected.
4. Send a pull request. Make sure to add yourself to AUTHORS.