Install & Compatibility
Where this runs
tested against v4.0.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
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.712s · 44.6MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 4.6s · import 0.668s · 44MB
43MB installed
● package 43MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Brevo
✓ from brevo import Brevo
✗ from brevo_python import Brevo
Version 4.x of the SDK uses `from brevo import Brevo`. Previous versions (v1.x) used `from brevo_python import Brevo` or `from sib_api_v3_sdk import ApiClient`.
ApiError
✓ from brevo.exceptions import ApiError
✗ from brevo_python.rest import ApiException
The exception class for API errors changed with the v4 rewrite.
This quickstart initializes the Brevo client using an API key from an environment variable and then retrieves basic account details and a list of contacts to verify connectivity.
import os
from brevo import Brevo
from brevo.exceptions import ApiError
# Set your Brevo API key as an environment variable (e.g., BREVO_API_KEY)
api_key = os.environ.get("BREVO_API_KEY", "")
if not api_key:
print("Error: BREVO_API_KEY environment variable not set. Please set it to your Brevo API key.")
else:
try:
client = Brevo(api_key=api_key)
# Example: Get account details
account = client.account.get_account()
print(f"Successfully connected to Brevo API. Account email: {account.email}")
print(f"Company name: {account.company_name}")
# Example: Get contacts (first 10)
contacts_response = client.contacts.get_contacts(limit=10)
print(f"Found {len(contacts_response.contacts)} contacts.")
if contacts_response.contacts:
print(f"First contact email: {contacts_response.contacts[0].email}")
except ApiError as e:
print(f"Brevo API Error: {e}")
if "Unauthorized" in str(e):
print("Please check if your BREVO_API_KEY is valid and has the necessary permissions.")
except Exception as e:
print(f"An unexpected error occurred: {e}")
Debug
Known issues
breakingVersion 4.x of `brevo-python` is a complete rewrite with significant breaking changes compared to v1.x. The module name changed from `brevo_python` to `brevo`, and the client object structure, API call methods, and exception handling are entirely different.fixRefer to the official Brevo SDK documentation or migration guides for v4. Update all import statements (e.g., `from brevo import Brevo`), client instantiation, and method calls.
affects: >=4.0.0 (when migrating from <4.0.0)
gotchaPrior to v4.0.9, calling `client.contacts.create_contact(..., update_enabled=True)` for an existing contact would incorrectly raise an `ApiError` even though the Brevo API returned a successful 204 No Content response.fixUpgrade to `brevo-python>=4.0.9`. If unable to upgrade, you may need to explicitly catch `ApiError` and inspect its message or status code to handle this specific scenario.
affects: 4.0.0 - 4.0.8
gotchaIn `get_process` and `get_processes` responses, the `duplicate_email_id` field's expected type was changed from `Optional[int]` to `Optional[str]` (which is a URL) to match the actual API response.fixUpgrade to `brevo-python>=4.0.10`. On older versions, attempts to deserialize this field might fail if the API returns a string when an integer is expected, leading to `TypeError` or `ValidationError`.
affects: 4.0.0 - 4.0.9
gotchaThe `status` field for `get_process` and `get_processes` endpoints did not include the `"in_process"` literal type prior to v4.0.10, causing deserialization failures for active processes.fixUpgrade to `brevo-python>=4.0.10`. If stuck on an older version, you might encounter deserialization errors when retrieving processes that are currently in progress.
affects: 4.0.0 - 4.0.9
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'brevo_python'
You are attempting to use import statements from the v1.x SDK (`brevo_python`) with the v4.x SDK (`brevo-python`) installed. The module name changed in version 4.
fixUpdate your import statements. For example, change `from brevo_python import Brevo` to `from brevo import Brevo`.
brevo.exceptions.ApiError: (401) Unauthorized
The API key provided is either missing, incorrect, or does not have the necessary permissions for the requested operation.
fixEnsure your `BREVO_API_KEY` environment variable or the API key passed to `Brevo()` is correct and valid. Verify it has the required permissions in your Brevo account.
brevo.exceptions.ApiError: (400) The contact already exists.
This error message might occur when using `create_contact` with `update_enabled=True` on `brevo-python` versions before 4.0.9, even though the Brevo API successfully updated the contact.
fixUpgrade to `brevo-python>=4.0.9`. This bug was fixed to correctly return a successful (empty) response without raising an `ApiError` in this scenario.
TypeError: Expected <class 'int'>, got <class 'str'>
This error can occur when parsing the `duplicate_email_id` field from `get_process` or `get_processes` responses on SDK versions before 4.0.10, due to a type mismatch with the actual API response (URL string vs. expected integer).
fixUpgrade to `brevo-python>=4.0.10` to correctly handle the `duplicate_email_id` as an `Optional[str]`.
Upgrade
Version history
4.0.10latest on PyPI · released Apr 10, 2026
Audit
Dependencies
httpxrequiredUnderlying HTTP client for network requests.
pydanticrequiredUsed for data validation and parsing API responses into Python models.