Registry / communication / sparkpost

sparkpost

JSON →
library1.3.10pypypi✓ verified 85d ago

The `sparkpost` library is the official Python API client for SparkPost, an enterprise email sending and analytics platform. It provides a straightforward interface to interact with SparkPost's REST API, covering functionalities like sending transmissions, managing templates, and accessing suppression lists. It is actively maintained, with regular updates focused on bug fixes, security enhancements, and new API features. The current version is 1.3.10.

pip install sparkpost
INSTALL
IMPORT
SIG · SPARKPOST
S
sparkpost
communicationpythonv1.3.10
Install
2.3s avg
Import
41ms
Disk
20MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.3.10 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.910 runs
installs and imports cleanly · install 0.0s · import 0.045s · 21.6MB
glibc
py 3.103.910 runs
installs and imports cleanly · install 2.3s · import 0.038s · 22MB
20MB installed
● package 20MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

SparkPost
from sparkpost import SparkPost
The main client class for interacting with the SparkPost API.

This quickstart demonstrates how to initialize the SparkPost client and send a simple HTML email. Ensure your `SPARKPOST_API_KEY`, `SPARKPOST_FROM_EMAIL`, and `SPARKPOST_TEST_EMAIL` environment variables are set. The example includes basic error handling for `SparkPostAPIException`.

import os from sparkpost import SparkPost from sparkpost.exceptions import SparkPostAPIException # Retrieve SparkPost API key and other details from environment variables # It is highly recommended to use environment variables or a secret management system sparkpost_api_key = os.environ.get('SPARKPOST_API_KEY', 'YOUR_SPARKPOST_API_KEY') from_email = os.environ.get('SPARKPOST_FROM_EMAIL', 'test@example.com') recipient_email = os.environ.get('SPARKPOST_TEST_EMAIL', 'recipient@example.com') if not sparkpost_api_key or sparkpost_api_key == 'YOUR_SPARKPOST_API_KEY': print("WARNING: SPARKPOST_API_KEY environment variable not set or placeholder used.\nCannot send email without a valid API key.") else: try: sp = SparkPost(sparkpost_api_key) response = sp.transmissions.send( recipients=[{'address': recipient_email}], html='<p>Hello from <b>SparkPost Python</b> client!</p>', from_email=from_email, subject='Test Email from Python SparkPost' ) print("Email sent successfully!") print(f"Transmission ID: {response['results']['id']}") print(f"Accepted recipients: {response['results']['total_accepted_recipients']}") except SparkPostAPIException as e: print(f"SparkPost API Error: {e.status} {e.message} - {e.errors}") except Exception as e: print(f"An unexpected error occurred: {e}")
Debug
Known issues
deprecatedThe direct URI parameter support for the 'transmissions list' endpoint has been deprecated. While still functional, it's recommended to migrate to updated methods or client versions that handle this gracefully.
fix
Consult the latest SparkPost API documentation or client examples for the recommended way to query transmission lists, typically involving query parameters within a structured call rather than direct URI parameters.
affects: >=1.3.5
gotchaWhen handling API errors, ensure you catch `SparkPostAPIException` for specific details. Older versions (pre-1.3.3) had issues returning proper exceptions for some underlying API errors, potentially masking the true problem.
fix
Always wrap API calls in a `try...except SparkPostAPIException as e:` block. Upgrade to version 1.3.3 or newer to ensure more reliable exception reporting from the API.
affects: <1.3.3
gotchaSending emails with non-ASCII characters (e.g., emojis) in the message body may have inconsistent behavior across different minor versions if not handled correctly by the library's encoding.
fix
Ensure you are on version 1.3.1 or later to benefit from fixes related to emoji handling (issue #114), but note a partial revert in 1.3.2 (issue #129) that was later investigated. For robust handling, always ensure your content is UTF-8 encoded and update to the latest patch version.
affects: 1.3.1 - 1.3.2
Errors
Common errors & fixes
sparkpost.exceptions.SparkPostAPIException: 401 Unauthorized
The SparkPost API key provided is missing, invalid, or does not have the necessary permissions for the requested operation.
fix
Verify that the `SPARKPOST_API_KEY` environment variable or the key passed to `SparkPost()` constructor is correct and active. Ensure it has the 'Send via SMTP' and 'Transmissions: Read/Write' permissions (or similar, depending on the operation).
sparkpost.exceptions.SparkPostAPIException: 400 Bad Request - 'recipient address is required'
The `recipients` parameter in the `transmissions.send()` call is either empty, malformed, or missing the 'address' key for one or more recipients.
fix
Ensure the `recipients` list contains dictionaries, each with at least an 'address' key and a valid email string. Example: `recipients=[{'address': 'test@example.com'}]`.
ImportError: cannot import name 'SparkPost' from 'sparkpost'
Python cannot find the `SparkPost` class within the `sparkpost` package. This usually means the library is not installed, or there's a local file/directory named `sparkpost.py` or `sparkpost` shadowing the actual library.
fix
First, ensure the library is installed with `pip install sparkpost`. If the problem persists, check your project directory and Python path for any files or directories named `sparkpost.py` or `sparkpost` that might be causing a conflict.
Upgrade
Version history
1.3.10latest on PyPI · released Nov 9, 2021
Audit
Dependencies
requestsrequiredUsed for making HTTP requests to the SparkPost API.
Agent activity
23 hits · last 30 days
node
20
OpenAI (training)
1
Resources
sparkpost — pip install sparkpost · libregistry