{"id":10246,"library":"sparkpost","title":"SparkPost Python API Client","description":"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.","status":"active","version":"1.3.10","language":"en","source_language":"en","source_url":"https://github.com/SparkPost/python-sparkpost","tags":["email","api-client","transactional-email"],"install":[{"cmd":"pip install sparkpost","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Used for making HTTP requests to the SparkPost API.","package":"requests","optional":false}],"imports":[{"note":"The main client class for interacting with the SparkPost API.","symbol":"SparkPost","correct":"from sparkpost import SparkPost"}],"quickstart":{"code":"import os\nfrom sparkpost import SparkPost\nfrom sparkpost.exceptions import SparkPostAPIException\n\n# Retrieve SparkPost API key and other details from environment variables\n# It is highly recommended to use environment variables or a secret management system\nsparkpost_api_key = os.environ.get('SPARKPOST_API_KEY', 'YOUR_SPARKPOST_API_KEY')\nfrom_email = os.environ.get('SPARKPOST_FROM_EMAIL', 'test@example.com')\nrecipient_email = os.environ.get('SPARKPOST_TEST_EMAIL', 'recipient@example.com')\n\nif not sparkpost_api_key or sparkpost_api_key == 'YOUR_SPARKPOST_API_KEY':\n    print(\"WARNING: SPARKPOST_API_KEY environment variable not set or placeholder used.\\nCannot send email without a valid API key.\")\nelse:\n    try:\n        sp = SparkPost(sparkpost_api_key)\n        \n        response = sp.transmissions.send(\n            recipients=[{'address': recipient_email}],\n            html='<p>Hello from <b>SparkPost Python</b> client!</p>',\n            from_email=from_email,\n            subject='Test Email from Python SparkPost'\n        )\n\n        print(\"Email sent successfully!\")\n        print(f\"Transmission ID: {response['results']['id']}\")\n        print(f\"Accepted recipients: {response['results']['total_accepted_recipients']}\")\n    except SparkPostAPIException as e:\n        print(f\"SparkPost API Error: {e.status} {e.message} - {e.errors}\")\n    except Exception as e:\n        print(f\"An unexpected error occurred: {e}\")","lang":"python","description":"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`."},"warnings":[{"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.","message":"The 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.","severity":"deprecated","affected_versions":">=1.3.5"},{"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.","message":"When 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.","severity":"gotcha","affected_versions":"<1.3.3"},{"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.","message":"Sending 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.","severity":"gotcha","affected_versions":"1.3.1 - 1.3.2"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"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).","cause":"The SparkPost API key provided is missing, invalid, or does not have the necessary permissions for the requested operation.","error":"sparkpost.exceptions.SparkPostAPIException: 401 Unauthorized"},{"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'}]`.","cause":"The `recipients` parameter in the `transmissions.send()` call is either empty, malformed, or missing the 'address' key for one or more recipients.","error":"sparkpost.exceptions.SparkPostAPIException: 400 Bad Request - 'recipient address is required'"},{"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.","cause":"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.","error":"ImportError: cannot import name 'SparkPost' from 'sparkpost'"}]}