From 7030e43ced27c423f68597c91877d1df3f0c61e3 Mon Sep 17 00:00:00 2001 From: Richard Leland Date: Thu, 25 May 2017 12:21:18 -0400 Subject: [PATCH] Update docs for 2.x (#152) * Update readme with 2.x usage * Update sphinx docs for 2.x * Remove examples for resources no longer in 2.x * Remove example of base resource for 2.x * Update send transmission example * Remove deprecated transmissions calls * Update transmissions examples for 2.x * Add start_time example using pendulum * Show how to extract error attributes for exceptions --- README.rst | 146 ++++++++++++--- docs/api/recipient_lists.rst | 7 - docs/api/suppression_list.rst | 7 - docs/api/templates.rst | 7 - docs/conf.py | 108 +++++------ docs/django/backend.rst | 99 ---------- docs/index.rst | 176 ++++++++++++++++-- docs/resources/metrics.rst | 34 ---- docs/resources/recipient_lists.rst | 83 --------- docs/resources/suppression_list.rst | 68 ------- docs/resources/templates.rst | 69 ------- docs/resources/transmissions.rst | 158 +++++++++------- examples/base_resource.py | 18 -- .../recipient_lists/create_recipient_list.py | 25 --- .../recipient_lists/delete_recipient_list.py | 5 - .../recipient_lists/get_recipient_list.py | 5 - .../get_recipient_list_with_recipients.py | 5 - .../recipient_lists/list_recipient_lists.py | 5 - .../recipient_lists/update_recipient_list.py | 25 --- .../create_suppression_entries_bulk.py | 25 --- .../create_suppression_entry.py | 10 - .../delete_suppression_entry.py | 5 - .../suppression_list/get_suppression_entry.py | 5 - .../list_suppression_entries.py | 9 - .../update_suppression_entries_bulk.py | 25 --- .../update_suppression_enty.py | 10 - examples/templates/create_template.py | 13 -- examples/templates/delete_template.py | 5 - examples/templates/get_template.py | 5 - examples/templates/list_templates.py | 5 - examples/templates/preview_draft_template.py | 9 - examples/templates/preview_template.py | 9 - examples/templates/update_template.py | 11 -- examples/transmissions/find_transmission.py | 5 - examples/transmissions/get_transmissions.py | 5 - examples/transmissions/handle_exception.py | 26 ++- .../transmissions/schedule_transmission.py | 43 ++--- examples/transmissions/send_transmission.py | 54 +++--- .../transmissions/transmission_stored_list.py | 31 ++- .../transmission_stored_template.py | 10 +- 40 files changed, 508 insertions(+), 862 deletions(-) delete mode 100644 docs/api/recipient_lists.rst delete mode 100644 docs/api/suppression_list.rst delete mode 100644 docs/api/templates.rst delete mode 100644 docs/django/backend.rst delete mode 100644 docs/resources/metrics.rst delete mode 100644 docs/resources/recipient_lists.rst delete mode 100644 docs/resources/suppression_list.rst delete mode 100644 docs/resources/templates.rst delete mode 100644 examples/base_resource.py delete mode 100644 examples/recipient_lists/create_recipient_list.py delete mode 100644 examples/recipient_lists/delete_recipient_list.py delete mode 100644 examples/recipient_lists/get_recipient_list.py delete mode 100644 examples/recipient_lists/get_recipient_list_with_recipients.py delete mode 100644 examples/recipient_lists/list_recipient_lists.py delete mode 100644 examples/recipient_lists/update_recipient_list.py delete mode 100644 examples/suppression_list/create_suppression_entries_bulk.py delete mode 100644 examples/suppression_list/create_suppression_entry.py delete mode 100644 examples/suppression_list/delete_suppression_entry.py delete mode 100644 examples/suppression_list/get_suppression_entry.py delete mode 100644 examples/suppression_list/list_suppression_entries.py delete mode 100644 examples/suppression_list/update_suppression_entries_bulk.py delete mode 100644 examples/suppression_list/update_suppression_enty.py delete mode 100644 examples/templates/create_template.py delete mode 100644 examples/templates/delete_template.py delete mode 100644 examples/templates/get_template.py delete mode 100644 examples/templates/list_templates.py delete mode 100644 examples/templates/preview_draft_template.py delete mode 100644 examples/templates/preview_template.py delete mode 100644 examples/templates/update_template.py delete mode 100644 examples/transmissions/find_transmission.py delete mode 100644 examples/transmissions/get_transmissions.py diff --git a/README.rst b/README.rst index cacda11..f2860b4 100644 --- a/README.rst +++ b/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='

Hello world

', - 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': '

Hello world!

', + }, + }) 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 diff --git a/docs/api/recipient_lists.rst b/docs/api/recipient_lists.rst deleted file mode 100644 index d724576..0000000 --- a/docs/api/recipient_lists.rst +++ /dev/null @@ -1,7 +0,0 @@ -.. module:: sparkpost.recipient_lists - -:mod:`sparkpost.recipient_lists` -================================ - -.. autoclass:: RecipientLists - :members: diff --git a/docs/api/suppression_list.rst b/docs/api/suppression_list.rst deleted file mode 100644 index ce86428..0000000 --- a/docs/api/suppression_list.rst +++ /dev/null @@ -1,7 +0,0 @@ -.. module:: sparkpost.suppression_list - -:mod:`sparkpost.suppression_list` -================================= - -.. autoclass:: SuppressionList - :members: diff --git a/docs/api/templates.rst b/docs/api/templates.rst deleted file mode 100644 index cfa8ba8..0000000 --- a/docs/api/templates.rst +++ /dev/null @@ -1,7 +0,0 @@ -.. module:: sparkpost.templates - -:mod:`sparkpost.templates` -============================= - -.. autoclass:: Templates - :members: diff --git a/docs/conf.py b/docs/conf.py index 57dc59f..45bae73 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -19,12 +19,12 @@ # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. -#sys.path.insert(0, os.path.abspath('.')) +# sys.path.insert(0, os.path.abspath('.')) # -- General configuration ------------------------------------------------ # If your documentation needs a minimal Sphinx version, state it here. -#needs_sphinx = '1.0' +# needs_sphinx = '1.0' # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom @@ -43,7 +43,7 @@ source_suffix = '.rst' # The encoding of source files. -#source_encoding = 'utf-8-sig' +# source_encoding = 'utf-8-sig' # The master toctree document. master_doc = 'index' @@ -51,26 +51,26 @@ # General information about the project. now = datetime.datetime.now() project = u'python-sparkpost' -copyright = u'2014-{year}, Message Systems'.format(year=now.year) +copyright = u'2014-{year}, SparkPost'.format(year=now.year) # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the # built documents. # # The short X.Y version. -version = '1.3' +version = '2.0' # The full version, including alpha/beta/rc tags. -release = '1.3.5' +release = '2.0.dev1' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. -#language = None +# language = None # There are two options for replacing |today|: either, you set today to some # non-false value, then it is used: -#today = '' +# today = '' # Else, today_fmt is used as the format for a strftime call. -#today_fmt = '%B %d, %Y' +# today_fmt = '%B %d, %Y' # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. @@ -78,27 +78,27 @@ # The reST default role (used for this markup: `text`) to use for all # documents. -#default_role = None +# default_role = None # If true, '()' will be appended to :func: etc. cross-reference text. -#add_function_parentheses = True +# add_function_parentheses = True # If true, the current module name will be prepended to all description # unit titles (such as .. function::). -#add_module_names = True +# add_module_names = True # If true, sectionauthor and moduleauthor directives will be shown in the # output. They are ignored by default. -#show_authors = False +# show_authors = False # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' # A list of ignored prefixes for module index sorting. -#modindex_common_prefix = [] +# modindex_common_prefix = [] # If true, keep warnings as "system message" paragraphs in the built documents. -#keep_warnings = False +# keep_warnings = False # -- Options for HTML output ---------------------------------------------- @@ -116,26 +116,26 @@ # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. -#html_theme_options = {} +# html_theme_options = {} # Add any paths that contain custom themes here, relative to this directory. -#html_theme_path = [] +# html_theme_path = [] # The name for this set of Sphinx documents. If None, it defaults to # " v documentation". -#html_title = None +# html_title = None # A shorter title for the navigation bar. Default is the same as html_title. -#html_short_title = None +# html_short_title = None # The name of an image file (relative to this directory) to place at the top # of the sidebar. -#html_logo = None +# html_logo = None # The name of an image file (within the static path) to use as favicon of the # docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 # pixels large. -#html_favicon = None +# html_favicon = None # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, @@ -145,48 +145,48 @@ # Add any extra paths that contain custom files (such as robots.txt or # .htaccess) here, relative to this directory. These files are copied # directly to the root of the documentation. -#html_extra_path = [] +# html_extra_path = [] # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. -#html_last_updated_fmt = '%b %d, %Y' +# html_last_updated_fmt = '%b %d, %Y' # If true, SmartyPants will be used to convert quotes and dashes to # typographically correct entities. -#html_use_smartypants = True +# html_use_smartypants = True # Custom sidebar templates, maps document names to template names. -#html_sidebars = {} +# html_sidebars = {} # Additional templates that should be rendered to pages, maps page names to # template names. -#html_additional_pages = {} +# html_additional_pages = {} # If false, no module index is generated. -#html_domain_indices = True +# html_domain_indices = True # If false, no index is generated. -#html_use_index = True +# html_use_index = True # If true, the index is split into individual pages for each letter. -#html_split_index = False +# html_split_index = False # If true, links to the reST sources are added to the pages. -#html_show_sourcelink = True +# html_show_sourcelink = True # If true, "Created using Sphinx" is shown in the HTML footer. Default is True. -#html_show_sphinx = True +# html_show_sphinx = True # If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. -#html_show_copyright = True +# html_show_copyright = True # If true, an OpenSearch description file will be output, and all pages will # contain a tag referring to it. The value of this option must be the # base URL from which the finished HTML is served. -#html_use_opensearch = '' +# html_use_opensearch = '' # This is the file name suffix for HTML files (e.g. ".xhtml"). -#html_file_suffix = None +# html_file_suffix = None # Output file base name for HTML help builder. htmlhelp_basename = 'python-sparkpostdoc' @@ -195,14 +195,14 @@ # -- Options for LaTeX output --------------------------------------------- latex_elements = { -# The paper size ('letterpaper' or 'a4paper'). -#'papersize': 'letterpaper', + # The paper size ('letterpaper' or 'a4paper'). + # 'papersize': 'letterpaper', -# The font size ('10pt', '11pt' or '12pt'). -#'pointsize': '10pt', + # The font size ('10pt', '11pt' or '12pt'). + # 'pointsize': '10pt', -# Additional stuff for the LaTeX preamble. -#'preamble': '', + # Additional stuff for the LaTeX preamble. + # 'preamble': '', } # Grouping the document tree into LaTeX files. List of tuples @@ -210,28 +210,28 @@ # author, documentclass [howto, manual, or own class]). latex_documents = [ ('index', 'python-sparkpost.tex', u'python-sparkpost Documentation', - u'Message Systems', 'manual'), + u'SparkPost', 'manual'), ] # The name of an image file (relative to this directory) to place at the top of # the title page. -#latex_logo = None +# latex_logo = None # For "manual" documents, if this is true, then toplevel headings are parts, # not chapters. -#latex_use_parts = False +# latex_use_parts = False # If true, show page references after internal links. -#latex_show_pagerefs = False +# latex_show_pagerefs = False # If true, show URL addresses after external links. -#latex_show_urls = False +# latex_show_urls = False # Documents to append as an appendix to all manuals. -#latex_appendices = [] +# latex_appendices = [] # If false, no module index is generated. -#latex_domain_indices = True +# latex_domain_indices = True # -- Options for manual page output --------------------------------------- @@ -240,11 +240,11 @@ # (source start file, name, description, authors, manual section). man_pages = [ ('index', 'python-sparkpost', u'python-sparkpost Documentation', - [u'Message Systems'], 1) + [u'SparkPost'], 1) ] # If true, show URL addresses after external links. -#man_show_urls = False +# man_show_urls = False # -- Options for Texinfo output ------------------------------------------- @@ -254,18 +254,18 @@ # dir menu entry, description, category) texinfo_documents = [ ('index', 'python-sparkpost', u'python-sparkpost Documentation', - u'Message Systems', 'python-sparkpost', 'One line description of project.', + u'SparkPost', 'python-sparkpost', 'One line description of project.', 'Miscellaneous'), ] # Documents to append as an appendix to all manuals. -#texinfo_appendices = [] +# texinfo_appendices = [] # If false, no module index is generated. -#texinfo_domain_indices = True +# texinfo_domain_indices = True # How to display URL addresses: 'footnote', 'no', or 'inline'. -#texinfo_show_urls = 'footnote' +# texinfo_show_urls = 'footnote' # If true, do not generate a @detailmenu in the "Top" node's menu. -#texinfo_no_detailmenu = False +# texinfo_no_detailmenu = False diff --git a/docs/django/backend.rst b/docs/django/backend.rst deleted file mode 100644 index 1f7d511..0000000 --- a/docs/django/backend.rst +++ /dev/null @@ -1,99 +0,0 @@ -Django Email Backend -==================== - -The SparkPost python library comes with an email backend for Django. - -Configure Django ----------------- - -To configure Django to use SparkPost, put the following configuration in `settings.py` file. - -.. code-block:: python - - SPARKPOST_API_KEY = 'API_KEY' - EMAIL_BACKEND = 'sparkpost.django.email_backend.SparkPostEmailBackend' - -Replace *API_KEY* with an actual API key. - -You can also use `SPARKPOST_OPTIONS` to set options that will apply to every transmission. -For example: - -.. code-block:: python - - SPARKPOST_OPTIONS = { - 'track_opens': False, - 'track_clicks': False, - 'transactional': True, - } - - -Sending an email ----------------- - -Django is now configured to use the SparkPost email backend. You can now send mail using Django's `send_mail` method: - -.. code-block:: python - - from django.core.mail import send_mail - - send_mail( - subject='Hello from SparkPost', - message='Woo hoo! Sent from Django!', - from_email='from@yourdomain.com', - recipient_list=['to@example.com'], - html_message='

Hello Rock stars!

', - ) - - -You can also use `EmailMessage` or `EmailMultiAlternatives` class directly. That will give you access to more specific fileds like `template`: - -.. code-block:: python - - email = EmailMessage( - to=[ - { - "address": "to@example.com", - "substitution_data": { - "key": "value" - } - } - ], - from_email='test@from.com' - ) - email.template = 'template-id' - email.send() - -Or cc, bcc, reply to, or attachments fields: - -.. code-block:: python - - from django.core.mail import EmailMultiAlternatives - - email = EmailMultiAlternatives( - subject='hello from sparkpost', - body='Woo hoo! Sent from Django!', - from_email='from@yourdomain.com', - to=['to@example.com'], - cc=['ccone@example.com'], - bcc=['bccone@example.com'], - reply_to=['replyone@example.com'] - ) - - email.attach_alternative('

Woo hoo! Sent from Django!

', 'text/html') - email.attach('image.png', img_data, 'image/png') - email.send() - - -Supported version ------------------ -SparkPost will support all versions of Django that are within extended support period. Refer to `Django Supported Versions`_. - -.. _Django Supported Versions: https://www.djangoproject.com/download/#supported-versions - - -Additional documentation ------------------------- - -See our `Using SparkPost with Django`_ in support article. - -.. _Using SparkPost with Django: https://support.sparkpost.com/customer/en/portal/articles/2169630-using-sparkpost-with-django?b_id=7411 diff --git a/docs/index.rst b/docs/index.rst index b19fec8..f4c0e0a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,3 +1,4 @@ +=========================== SparkPost Python API client =========================== @@ -5,7 +6,7 @@ The super-mega-official Python package for using the SparkPost API. Installation ------------- +============ Install from PyPI using `pip`_: @@ -16,10 +17,10 @@ Install from PyPI using `pip`_: .. _pip: http://www.pip-installer.org/en/latest/ -Authorization -------------- +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 @@ -33,11 +34,159 @@ 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: + +.. code-block:: python + + 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': '

Hello world!

', + }, + }) + + print(response) + # outputs {u'total_accepted_recipients': 1, u'id': u'47960765679942446', u'total_rejected_recipients': 0} + +.. _transmissions API: https://developers.sparkpost.com/api/transmissions.html + +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 + + 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 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:: text + + requests + requests-toolbelt + +Then create or update your ``appengine_config.py`` file to include the following: + +.. code-block:: python + + 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. + +.. _some sample applications: https://github.com/search?q=org%3ASparkPost+google Resources ---------- +========= The following resources are available in python-sparkpost: @@ -49,7 +198,7 @@ The following resources are available in python-sparkpost: API reference -------------- +============= Auto-generated API reference for python-sparkpost: @@ -58,17 +207,6 @@ Auto-generated API reference for python-sparkpost: api -Using in Django ---------------- - -Configure Django to use SparkPost email backend - -.. toctree:: - :maxdepth: 2 - - django/backend - - Additional documentation ------------------------ @@ -78,7 +216,7 @@ The underlying SparkPost API is documented at the official `SparkPost API Refere 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 diff --git a/docs/resources/metrics.rst b/docs/resources/metrics.rst deleted file mode 100644 index eaef00c..0000000 --- a/docs/resources/metrics.rst +++ /dev/null @@ -1,34 +0,0 @@ -Metrics -======= - -Retrieve a list of campaigns ----------------------------- - -.. code-block:: python - - from sparkpost import SparkPost - - sp = SparkPost() - - sp.metrics.campaigns.list() - - -Retrieve a list of domains --------------------------- - -.. code-block:: python - - from sparkpost import SparkPost - - sp = SparkPost() - - sp.metrics.domains.list() - - -Additional documentation ------------------------- - -See the `SparkPost Metrics API Reference`_. - -.. _SparkPost Metrics API Reference: https://www.sparkpost.com/api#/reference/metrics - diff --git a/docs/resources/recipient_lists.rst b/docs/resources/recipient_lists.rst deleted file mode 100644 index 5ef507e..0000000 --- a/docs/resources/recipient_lists.rst +++ /dev/null @@ -1,83 +0,0 @@ -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 diff --git a/docs/resources/suppression_list.rst b/docs/resources/suppression_list.rst deleted file mode 100644 index 412eb3b..0000000 --- a/docs/resources/suppression_list.rst +++ /dev/null @@ -1,68 +0,0 @@ -Suppression List -================ - -Let's use the underlying `suppression_list API`_ to create a suppression entry: - -.. code-block:: python - - from sparkpost import SparkPost - - sp = SparkPost() - - response = sp.suppression_list.create({ - "email": "test@test.com" - "transactional": False, - "non_transactional": True, - "description": "User requested to not receive any non-transactional emails." - }) - - print(response) - # outputs {u'message': u'Recipient successfully created'} - -.. _suppression_list API: https://www.sparkpost.com/api#/reference/suppression-list - - -Get a suppression entry ------------------------ - -.. code-block:: python - - from sparkpost import SparkPost - - sp = SparkPost() - - sp.suppression_list.get('test@test.com') - - -List suppression entries ------------------------- - -.. code-block:: python - - from sparkpost import SparkPost - - sp = SparkPost() - - sp.suppression_list.list() - - -API reference -------------- - -:doc:`/api/suppression_list` - - -Further examples ----------------- - -See the `python-sparkpost suppression_list examples`_. - -.. _python-sparkpost suppression_list examples: https://github.com/SparkPost/python-sparkpost/tree/master/examples/suppression_list - - -Additional documentation ------------------------- - -See the `SparkPost Suppression List API Reference`_. - -.. _SparkPost Suppression List API Reference: https://www.sparkpost.com/api#/reference/suppression-list diff --git a/docs/resources/templates.rst b/docs/resources/templates.rst deleted file mode 100644 index 7202c78..0000000 --- a/docs/resources/templates.rst +++ /dev/null @@ -1,69 +0,0 @@ -Templates -============= - -Let's use the underlying `templates API`_ to create a template: - -.. code-block:: python - - from sparkpost import SparkPost - - sp = SparkPost() - - response = sp.templates.create( - id='TEST_ID', - name='Test Template', - from_email='test@test.com', - subject='Test email template!', - html='This is a test email template!' - ) - - print(response) - # outputs {u'id': u'TEST_ID'} - -.. _templates API: https://www.sparkpost.com/api#/reference/templates - - -Retrieve a template ------------------------ - -.. code-block:: python - - from sparkpost import SparkPost - - sp = SparkPost() - - sp.templates.get('my-template-id') - - -List all templates ----------------------- - -.. code-block:: python - - from sparkpost import SparkPost - - sp = SparkPost() - - sp.templates.list() - - -API reference -------------- - -:doc:`/api/templates` - - -Further examples ----------------- - -See the `python-sparkpost templates examples`_. - -.. _python-sparkpost templates examples: https://github.com/SparkPost/python-sparkpost/tree/master/examples/templates - - -Additional documentation ------------------------- - -See the `SparkPost Templates API Reference`_. - -.. _SparkPost Templates API Reference: https://www.sparkpost.com/api#/reference/templates diff --git a/docs/resources/transmissions.rst b/docs/resources/transmissions.rst index ca91063..e313328 100644 --- a/docs/resources/transmissions.rst +++ b/docs/resources/transmissions.rst @@ -9,19 +9,25 @@ Here at SparkPost, our messages are known as transmissions. Let's use the underl sp = SparkPost() - response = sp.transmissions.send( - recipients=['someone@somedomain.com'], - html='

Hello world

', - from_email='test@sparkpostbox.com', - subject='Hello from python-sparkpost', - track_opens=True, - track_clicks=True - ) + 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': '

Hello world!

', + }, + }) 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 Send a transmission @@ -36,15 +42,20 @@ Using inline templates and/or recipients sp = SparkPost() - sp.transmissions.send( - recipients=['someone@somedomain.com'], - text="Hello world", - html='

Hello world

', - from_email='test@sparkpostbox.com', - subject='Hello from python-sparkpost', - track_opens=True, - track_clicks=True - ) + 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': '

Hello world!

', + }, + }) Including cc, bcc @@ -56,17 +67,22 @@ Including cc, bcc sp = SparkPost() - sp.transmissions.send( - recipients=['someone@somedomain.com'], - cc=['carboncopy@somedomain.com'], - bcc=['blindcarboncopy@somedomain.com'], - text="Hello world", - html='

Hello world

', - from_email='test@sparkpostbox.com', - subject='Hello from python-sparkpost', - track_opens=True, - track_clicks=True - ) + response = sp.transmissions.post({ + 'options': { + 'sandbox': True, + 'open_tracking': True, + 'click_tracking': True, + }, + 'recipients': ['someone@somedomain.com'], + 'cc': ['carboncopy@somedomain.com'], + 'bcc': ['blindcarboncopy@somedomain.com'], + 'content': { + 'from': 'test@sparkpostbox.com', + 'subject': 'Hello from python-sparkpost', + 'text': 'Hello world!', + 'html': '

Hello world!

', + }, + }) Sending an attachment @@ -78,22 +94,27 @@ Sending an attachment sp = SparkPost() - sp.transmissions.send( - recipients=['someone@somedomain.com'], - text="Hello world", - html='

Hello world

', - from_email='test@sparkpostbox.com', - subject='Hello from python-sparkpost', - track_opens=True, - track_clicks=True, - attachments=[ - { - "name": "test.txt", - "type": "text/plain", - "filename": "/home/sparkpost/a-file.txt" - } + 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': '

Hello world!

', + 'attachments': [ + { + 'name': 'test.txt', + 'type': 'text/plain', + 'filename': '/home/sparkpost/a-file.txt' + } ] - ) + }, + }) Using substitution data @@ -109,18 +130,23 @@ Using substitution data sp = SparkPost() - sp.transmissions.send( - recipients=['someone@somedomain.com'], - text="Hello {{name}}", - html='

Hello {{name}}

', - from_email='test@sparkpostbox.com', - subject='Hello from python-sparkpost', - track_opens=True, - track_clicks=True, - substitution_data={ - 'name': 'Sparky' - } - ) + 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 {{name}}!', + 'html': '

Hello {{name}}!

', + }, + 'substitution_data': { + 'name': 'Sparky' + }, + }) Using a stored template @@ -132,10 +158,10 @@ Using a stored template sp = SparkPost() - sp.transmissions.send( - recipients=['someone@somedomain.com'], - template='my-template-id' - ) + response = sp.transmissions.post({ + 'recipients': ['someone@somedomain.com'], + 'template_id': 'my-template-id', + }) Using a stored recipient list @@ -147,10 +173,10 @@ Using a stored recipient list sp = SparkPost() - sp.transmissions.send( - recipient_list='my-recipient-list', - template='my-template-id' - ) + response = sp.transmissions.post({ + 'recipients': 'my-recipient-list', + 'template_id': 'my-template-id', + }) Retrieve a transmission @@ -174,7 +200,7 @@ List all transmissions sp = SparkPost() - sp.transmissions.list() + sp.transmissions.get() API reference @@ -196,5 +222,5 @@ Additional documentation See the `SparkPost Transmissions API Reference`_. -.. _SparkPost Transmissions API Reference: https://www.sparkpost.com/api#/reference/transmissions +.. _SparkPost Transmissions API Reference: https://developers.sparkpost.com/api/transmissions.html diff --git a/examples/base_resource.py b/examples/base_resource.py deleted file mode 100644 index 307d9ac..0000000 --- a/examples/base_resource.py +++ /dev/null @@ -1,18 +0,0 @@ -import os - -from sparkpost.base import Resource - - -class Webhooks(Resource): - key = "webhooks" - - def list(self, **kwargs): - results = self.request('GET', self.uri, **kwargs) - return results - - -api_key = os.environ.get('SPARKPOST_API_KEY', None) -webhooks = Webhooks('https://api.sparkpost.com/api/v1', api_key) - -# returns a list of webhooks for your account -print(webhooks.list()) diff --git a/examples/recipient_lists/create_recipient_list.py b/examples/recipient_lists/create_recipient_list.py deleted file mode 100644 index ca534ea..0000000 --- a/examples/recipient_lists/create_recipient_list.py +++ /dev/null @@ -1,25 +0,0 @@ -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) diff --git a/examples/recipient_lists/delete_recipient_list.py b/examples/recipient_lists/delete_recipient_list.py deleted file mode 100644 index 8ba67cf..0000000 --- a/examples/recipient_lists/delete_recipient_list.py +++ /dev/null @@ -1,5 +0,0 @@ -from sparkpost import SparkPost - -sp = SparkPost() -result = sp.recipient_lists.delete('list_id') -print(result) diff --git a/examples/recipient_lists/get_recipient_list.py b/examples/recipient_lists/get_recipient_list.py deleted file mode 100644 index 554b7b8..0000000 --- a/examples/recipient_lists/get_recipient_list.py +++ /dev/null @@ -1,5 +0,0 @@ -from sparkpost import SparkPost - -sp = SparkPost() -recipient_list = sp.recipient_lists.get('list_id') -print(recipient_list) diff --git a/examples/recipient_lists/get_recipient_list_with_recipients.py b/examples/recipient_lists/get_recipient_list_with_recipients.py deleted file mode 100644 index c3d4000..0000000 --- a/examples/recipient_lists/get_recipient_list_with_recipients.py +++ /dev/null @@ -1,5 +0,0 @@ -from sparkpost import SparkPost - -sp = SparkPost() -recipient_list = sp.recipient_lists.get('list_id', True) -print(recipient_list) diff --git a/examples/recipient_lists/list_recipient_lists.py b/examples/recipient_lists/list_recipient_lists.py deleted file mode 100644 index 2bbe364..0000000 --- a/examples/recipient_lists/list_recipient_lists.py +++ /dev/null @@ -1,5 +0,0 @@ -from sparkpost import SparkPost - -sp = SparkPost() -recipient_lists = sp.recipient_lists.list() -print(recipient_lists) diff --git a/examples/recipient_lists/update_recipient_list.py b/examples/recipient_lists/update_recipient_list.py deleted file mode 100644 index 32d8625..0000000 --- a/examples/recipient_lists/update_recipient_list.py +++ /dev/null @@ -1,25 +0,0 @@ -from sparkpost import SparkPost - -sp = SparkPost() -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) diff --git a/examples/suppression_list/create_suppression_entries_bulk.py b/examples/suppression_list/create_suppression_entries_bulk.py deleted file mode 100644 index e40d8db..0000000 --- a/examples/suppression_list/create_suppression_entries_bulk.py +++ /dev/null @@ -1,25 +0,0 @@ -from sparkpost import SparkPost - -sp = SparkPost() -recipients = [ - { - 'email': 'test1@test.com', - 'transactional': False, - 'non_transactional': True, - 'description': 'Test description 1' - }, - { - 'email': 'test2@test.com', - 'transactional': True, - 'non_transactional': True, - 'description': 'Test description 2' - }, - { - 'email': 'test3@test.com', - 'transactional': True, - 'non_transactional': False, - 'description': 'Test description 3' - } -] -result = sp.suppression_list.create(recipients) -print(result) diff --git a/examples/suppression_list/create_suppression_entry.py b/examples/suppression_list/create_suppression_entry.py deleted file mode 100644 index b3f988d..0000000 --- a/examples/suppression_list/create_suppression_entry.py +++ /dev/null @@ -1,10 +0,0 @@ -from sparkpost import SparkPost - -sp = SparkPost() -result = sp.suppression_list.create({ - 'email': 'test@test.com', - 'transactional': False, - 'non_transactional': True, - 'description': 'Test description' -}) -print(result) diff --git a/examples/suppression_list/delete_suppression_entry.py b/examples/suppression_list/delete_suppression_entry.py deleted file mode 100644 index e4894ec..0000000 --- a/examples/suppression_list/delete_suppression_entry.py +++ /dev/null @@ -1,5 +0,0 @@ -from sparkpost import SparkPost - -sp = SparkPost() -result = sp.suppression_list.delete('test@test.com') -print(result) diff --git a/examples/suppression_list/get_suppression_entry.py b/examples/suppression_list/get_suppression_entry.py deleted file mode 100644 index ea32f64..0000000 --- a/examples/suppression_list/get_suppression_entry.py +++ /dev/null @@ -1,5 +0,0 @@ -from sparkpost import SparkPost - -sp = SparkPost() -entry = sp.suppression_list.get('test@test.com') -print(entry) diff --git a/examples/suppression_list/list_suppression_entries.py b/examples/suppression_list/list_suppression_entries.py deleted file mode 100644 index d519068..0000000 --- a/examples/suppression_list/list_suppression_entries.py +++ /dev/null @@ -1,9 +0,0 @@ -from sparkpost import SparkPost - -sp = SparkPost() -results = sp.suppression_list.list( - from_date='2015-05-07T00:00:00+0000', - to_date='2015-05-07T23:59:59+0000', - limit=5 -) -print(results) diff --git a/examples/suppression_list/update_suppression_entries_bulk.py b/examples/suppression_list/update_suppression_entries_bulk.py deleted file mode 100644 index 88d0558..0000000 --- a/examples/suppression_list/update_suppression_entries_bulk.py +++ /dev/null @@ -1,25 +0,0 @@ -from sparkpost import SparkPost - -sp = SparkPost() -recipients = [ - { - 'email': 'test1@test.com', - 'transactional': False, - 'non_transactional': True, - 'description': 'Test description 1' - }, - { - 'email': 'test2@test.com', - 'transactional': True, - 'non_transactional': True, - 'description': 'Test description 2' - }, - { - 'email': 'test3@test.com', - 'transactional': True, - 'non_transactional': False, - 'description': 'Test description 3' - } -] -result = sp.suppression_list.update(recipients) -print(result) diff --git a/examples/suppression_list/update_suppression_enty.py b/examples/suppression_list/update_suppression_enty.py deleted file mode 100644 index cc8c7bf..0000000 --- a/examples/suppression_list/update_suppression_enty.py +++ /dev/null @@ -1,10 +0,0 @@ -from sparkpost import SparkPost - -sp = SparkPost() -result = sp.suppression_list.update({ - 'email': 'test@test.com', - 'transactional': False, - 'non_transactional': True, - 'description': 'Test description' -}) -print(result) diff --git a/examples/templates/create_template.py b/examples/templates/create_template.py deleted file mode 100644 index 6b38da7..0000000 --- a/examples/templates/create_template.py +++ /dev/null @@ -1,13 +0,0 @@ -from sparkpost import SparkPost - -sp = SparkPost() - -response = sp.templates.create( - id='TEST_ID', - name='Test Template', - from_email='test@test.com', - subject='Test email template!', - html='This is a test email template!' -) - -print(response) diff --git a/examples/templates/delete_template.py b/examples/templates/delete_template.py deleted file mode 100644 index f035ace..0000000 --- a/examples/templates/delete_template.py +++ /dev/null @@ -1,5 +0,0 @@ -from sparkpost import SparkPost - -sp = SparkPost() -result = sp.templates.delete('template_id') -print(result) diff --git a/examples/templates/get_template.py b/examples/templates/get_template.py deleted file mode 100644 index b2a1078..0000000 --- a/examples/templates/get_template.py +++ /dev/null @@ -1,5 +0,0 @@ -from sparkpost import SparkPost - -sp = SparkPost() -template = sp.templates.get('template_id') -print(template) diff --git a/examples/templates/list_templates.py b/examples/templates/list_templates.py deleted file mode 100644 index ec9ad45..0000000 --- a/examples/templates/list_templates.py +++ /dev/null @@ -1,5 +0,0 @@ -from sparkpost import SparkPost - -sp = SparkPost() -template_list = sp.templates.list() -print(template_list) diff --git a/examples/templates/preview_draft_template.py b/examples/templates/preview_draft_template.py deleted file mode 100644 index 05ab84b..0000000 --- a/examples/templates/preview_draft_template.py +++ /dev/null @@ -1,9 +0,0 @@ -from sparkpost import SparkPost - -sp = SparkPost() -sub_data = { - 'first_name': 'John', - 'last_name': 'Doe' -} -template = sp.templates.preview('template_id', sub_data, True) -print(template) diff --git a/examples/templates/preview_template.py b/examples/templates/preview_template.py deleted file mode 100644 index 71ae4c7..0000000 --- a/examples/templates/preview_template.py +++ /dev/null @@ -1,9 +0,0 @@ -from sparkpost import SparkPost - -sp = SparkPost() -sub_data = { - 'first_name': 'John', - 'last_name': 'Doe' -} -template = sp.templates.preview('template_id', sub_data) -print(template) diff --git a/examples/templates/update_template.py b/examples/templates/update_template.py deleted file mode 100644 index 43c1765..0000000 --- a/examples/templates/update_template.py +++ /dev/null @@ -1,11 +0,0 @@ -from sparkpost import SparkPost - -sp = SparkPost() -response = sp.templates.update( - 'TEST_ID', - name='Test Template', - from_email='test@test.com', - subject='Updated Test email template!', - html='This is a test email template! Updated!' -) -print(response) diff --git a/examples/transmissions/find_transmission.py b/examples/transmissions/find_transmission.py deleted file mode 100644 index 5fe50c6..0000000 --- a/examples/transmissions/find_transmission.py +++ /dev/null @@ -1,5 +0,0 @@ -from sparkpost import SparkPost - -sp = SparkPost() -transmission = sp.transmissions.get('transmission_id') -print(transmission) diff --git a/examples/transmissions/get_transmissions.py b/examples/transmissions/get_transmissions.py deleted file mode 100644 index 9a34f01..0000000 --- a/examples/transmissions/get_transmissions.py +++ /dev/null @@ -1,5 +0,0 @@ -from sparkpost import SparkPost - -sp = SparkPost() -transmission_list = sp.transmissions.list() -print(transmission_list) diff --git a/examples/transmissions/handle_exception.py b/examples/transmissions/handle_exception.py index 558d21c..063fcbf 100644 --- a/examples/transmissions/handle_exception.py +++ b/examples/transmissions/handle_exception.py @@ -16,17 +16,27 @@ sp = SparkPost() try: - response = sp.transmissions.send( - recipients=['john.doe@example.com'], - text='Hello there', - from_email='Testing ', - subject='Testing python-sparkpost exceptions' - ) + response = sp.transmissions.post({ + 'recipients': ['john.doe@example.com'], + 'content': { + 'from': 'Testing ', + 'subject': 'Testing python-sparkpost exceptions', + 'text': 'Hello world!', + 'html': '

Hello world!

', + }, + 'campaign_id': 'python-sparkpost example', + }) except SparkPostAPIException as err: # http response status code print(err.status) + # list of formatted errors + print(err.errors) # python requests library response object # http://docs.python-requests.org/en/master/api/#requests.Response print(err.response.json()) - # list of formatted errors - print(err.errors) + # you can loop through the errors and extract message, code, description + for e in err.response.json()['errors']: + error_template = "{message} Code: {code} Description: {desc} \n" + print(error_template.format(message=e.get('message', ''), + code=e.get('code', 'none'), + desc=e.get('description', 'none'))) diff --git a/examples/transmissions/schedule_transmission.py b/examples/transmissions/schedule_transmission.py index 7fb8cab..b7afc4a 100644 --- a/examples/transmissions/schedule_transmission.py +++ b/examples/transmissions/schedule_transmission.py @@ -1,9 +1,22 @@ +""" +This example use the pendulum python package, which has a nice API for +datetime/timezone handling. You can use pytz or prepare your own datetimes. +""" +import pendulum from sparkpost import SparkPost +# create a datetime for two days from now +now = pendulum.now('Europe/Paris') +now = now.add(days=2) + sp = SparkPost() -response = sp.transmissions.send( - recipients=[ +response = sp.transmissions.post({ + 'options': { + 'sandbox': True, + 'start_time': now.to_iso8601_string(), + }, + 'recipients': [ 'postmaster@example.com', 'you@me.com', { @@ -13,25 +26,13 @@ } } ], - html='

Hello world {{name}}

', - text='Hello world {{name}}', - from_email='test@sparkpostbox.com', - subject='Example Script', - description='contrived example', - custom_headers={ - 'X-CUSTOM-HEADER': 'foo bar' - }, - track_opens=True, - track_clicks=True, - start_time='2015-11-06T09:10:00-05:00', - campaign='python-sparkpost example', - metadata={ - 'key': 'value', - 'arbitrary': 'values' + 'content': { + 'from': '"Test User" ', + 'subject': 'Hello from python-sparkpost', + 'text': 'Hello world!', + 'html': '

Hello world!

', }, - substitution_data={ - 'name': 'Example User' - } -) + 'campaign_id': 'python-sparkpost example', +}) print(response) diff --git a/examples/transmissions/send_transmission.py b/examples/transmissions/send_transmission.py index 6e6c25a..d274835 100644 --- a/examples/transmissions/send_transmission.py +++ b/examples/transmissions/send_transmission.py @@ -7,8 +7,13 @@ sp = SparkPost() -response = sp.transmissions.send( - recipients=[ +response = sp.transmissions.post({ + 'options': { + 'sandbox': True, + 'open_tracking': True, + 'click_tracking': True, + }, + 'recipients': [ 'postmaster@example.com', 'you@me.com', { @@ -18,32 +23,31 @@ } } ], - cc=['carboncopy@example.com'], - bcc=['blindcarboncopy@example.com'], - html='

Hello {{name}}

', - text='Hello {{name}}', - from_email='Test User ', - subject='Example Script', - description='contrived example', - custom_headers={ - 'X-CUSTOM-HEADER': 'foo bar' + 'cc': ['carboncopy@example.com'], + 'bcc': ['blindcarboncopy@example.com'], + 'content': { + 'from': '"Test User" ', + 'reply_to': 'no-reply@sparkpostmail.com', + 'subject': 'Hello from python-sparkpost', + 'text': 'Hello world!', + 'html': '

Hello world!

', + 'attachments': [ + { + 'name': 'test.txt', + 'type': 'text/plain', + 'filename': attachment_path + } + ], + 'headers': { + 'X-CUSTOM-HEADER': 'foo bar' + }, }, - track_opens=True, - track_clicks=True, - attachments=[ - { - "name": "test.txt", - "type": "text/plain", - "filename": attachment_path - } - ], - campaign='sdk example', - metadata={ + 'campaign_id': 'python-sparkpost example', + 'metadata': { 'key': 'value', 'arbitrary': 'values' }, - substitution_data={ + 'substitution_data': { 'name': 'Example User' }, - reply_to='no-reply@sparkpostmail.com' -) +}) diff --git a/examples/transmissions/transmission_stored_list.py b/examples/transmissions/transmission_stored_list.py index 38c66a8..b1526fe 100644 --- a/examples/transmissions/transmission_stored_list.py +++ b/examples/transmissions/transmission_stored_list.py @@ -2,23 +2,18 @@ sp = SparkPost() -response = sp.transmissions.send( - recipient_list='my_list', - html='

Hello world {{name}}

', - text='Hello world {{name}}', - from_email='test@sparkpostbox.com', - subject='Example Script', - description='contrived example', - custom_headers={ - 'X-CUSTOM-HEADER': 'foo bar' +response = sp.transmissions.post({ + 'options': { + 'sandbox': True, + 'open_tracking': True, + 'click_tracking': True, }, - campaign='sdk example', - metadata={ - 'key': 'value', - 'arbitrary': 'values' + 'recipients': 'my_list', + 'content': { + 'from': '"Test User" ', + 'subject': 'Hello from python-sparkpost', + 'text': 'Hello world!', + 'html': '

Hello world!

', }, - substitution_data={ - 'name': 'Example User' - }, - reply_to='no-reply@sparkpostmail.com' -) + 'campaign_id': 'python-sparkpost example', +}) diff --git a/examples/transmissions/transmission_stored_template.py b/examples/transmissions/transmission_stored_template.py index e58a604..8e32ef1 100644 --- a/examples/transmissions/transmission_stored_template.py +++ b/examples/transmissions/transmission_stored_template.py @@ -2,8 +2,8 @@ sp = SparkPost() -response = sp.transmissions.send( - recipients=['you@me.com'], - template='my-template-id', - use_draft_template=True -) +response = sp.transmissions.post({ + 'recipients': ['someone@somedomain.com'], + 'template_id': 'my-template-id', + 'use_draft_template': True, +})