Add return_path param to send() docs (#169)

Added return_path and updated some of the other docs.

Author: jgzamora

sparkpost/transmissions.py

@@ -157,32 +157,35 @@ def send(self, **kwargs):
         """
         Send a transmission based on the supplied parameters
 
-        :param list|dict recipients: If list it is an list of email addresses,
-            if dict ``{'address': {'name': 'Name', 'email': 'me' }}``
-        :param str recipient_list: ID of recipient list, if set recipients
-            above will be ignored
+        :param list|dict recipients: List of email addresses, or a dict:
+            ``{'address': {'name': 'Kyla', 'email': 'hello@example.com' }}``
+        :param str recipient_list: ID of recipient list. If this is set,
+            the `recipients` param will be ignored
         :param cc: List of email addresses to send carbon copy to
         :param bcc: List of email addresses to send blind carbon copy to
-        :param str template: ID of template. If set HTML or text will not be
-            used
-        :param bool use_draft_template: Default to False. Set to true if you
+        :param str template: ID of template to be used. Setting a template
+            overrides the HTML and text params
+        :param bool use_draft_template: Defaults to False. Set to true if you
             want to send a template that is a draft
         :param str html: HTML part of transmission
         :param str text: Text part of transmission
         :param str subject: Subject of transmission
         :param str from_email: Email that the transmission comes from. The
-            domain must be a verified sending domain to your account or
-            the transmission will fail. You can pass a from email or both
+            domain must be a verified sending domain belonging to your account
+            or the transmission will fail. You can pass a from email or both
             from name and from email - `testing@example.com` or
             `Test Email <testing@example.com>` will both work.
         :param str reply_to: Reply to of transmission
+        :param str return_path: Email address to use for envelope FROM. The
+            domain part of the return_path address must be a
+            CNAME-verified sending domain.
         :param str description: Description of transmission
         :param str campaign: Campaign of transmission
         :param dict metadata: Any data you want to send along with
             transmission, used in WebHooks
         :param dict substitution_data: Corresponds to substitutions in
             html/text content. See `substitutions reference
-            <https://developers.sparkpost.com/api/substitutions-reference.html>`_.
+            <https://developers.sparkpost.com/api/substitutions-reference>`_.
         :param attachments: List of dicts. For example:
 
             .. code-block:: python
@@ -238,15 +241,16 @@ def send(self, **kwargs):
             non-transactional for unsubscribe and suppression purposes
         :param bool skip_suppression: Whether or not to ignore customer
             suppression rules, for this transmission only. Only applicable if
-            your configuration supports this parameter. (SparkPost Elite only)
-        :param str ip_pool: The name of a dedicated IP pool associated with
+            your configuration supports this parameter. (Enterprise only)
+        :param str ip_pool: The ID of an IP pool associated with
             your account
         :param bool inline_css: Whether or not to perform CSS inlining
         :param dict custom_headers: Used to set any headers associated with
-            transmission
+            transmission. See `header notes
+            <https://developers.sparkpost.com/api/transmissions.html#header-header-notes>`_
 
-        :returns: a ``dict`` with the ID and number of accepted and rejected
-            recipients
+        :returns: a ``dict`` with the transmission ID and number of accepted
+            and rejected recipients
         :raises: :exc:`SparkPostAPIException` if transmission cannot be sent
         """
 
@@ -266,24 +270,23 @@ def get(self, transmission_id):
 
         :param str transmission_id: ID of the transmission you want to retrieve
 
-        :returns: the requested transmission if found
+        :returns: the requested transmission, if found
         :raises: :exc:`SparkPostAPIException` if transmission is not found
         """
         results = self._fetch_get(transmission_id)
         return results['transmission']
 
     def list(self, **kwargs):
         """
-        Get a list of your transmissions
+        Get a list of your transmissions. This method is deprecated.
 
         :param campaign_id: ID of the campaign used by the transmissions
         :param template_id: ID of the template used by the transmissions
 
         :returns: list of transmissions
         :raises: :exc:`SparkPostAPIException` if API call fails
         """
-        warn_msg = 'This endpoint is deprecated. For details, '
-        'check https://sparkpo.st/5qcj4.'
+        warn_msg = 'This method is deprecated.'
 
         warnings.warn(warn_msg, DeprecationWarning)
         return self.request('GET', self.uri, params=kwargs)