Brevo Python SDK

fern shield License: MIT PyPI version PyPI downloads Python versions

Website · API Reference · Support

Official SDK for the Brevo API.

Table of Contents

Documentation

API reference documentation is available here.

Installation

pip install brevo-python

Reference

A full reference for this library is available here.

Upgrading from v4.x

v5 is a major release. Most breaking changes come from an internal effort at Brevo to make endpoints, parameters and models more self-descriptive — so names, shapes and required fields convey intent without needing to cross-reference external docs (both for developers and for AI agents working against the Brevo API). Every change below applies symmetrically to both Brevo (sync) and AsyncBrevo.

v4.x remains supported. If you need to hold on v4 temporarily, pin it:

pip install "brevo-python>=4,<5"
View v4 → v5 migration guide

Breaking changes

Companies — get_companies(filters=...) renamed

  • The filters keyword is renamed to filters_attributes_name to match the wire format.
  • The old keyword is silently dropped, the request still succeeds, and the server returns an unfiltered list. Audit every call site.

Events — event.create_batch_events payload renamed

# v4
client.event.create_batch_events(request=[item1, item2])

# v5
client.event.create_batch_events(events=[item1, item2])

Item types renamed in lockstep: CreateBatchEventsRequestItem → CreateBatchEventsRequestEventsItem (and 5 sub-types).

Balance — get_contact_balances requires balance_definition_id

Balance — get_active_balances_api response shape changed

  • Response type replaced with GetLoyaltyBalanceProgramsPidActiveBalanceResponse.

Balance — begin_transaction.event_time type tightened

  • str → datetime. Type-checkers will fail on the old shape.

CRM — tasks.get_all_task_types returns a list (List[GetCrmTasktypesResponseItem] instead of GetCrmTasktypesResponse). Old .id / .title access on the response now fails.

Webhooks — create_webhook(events=...) is now optional / keyword-only. Positional callers break; switch to keyword arguments.

Webhooks — message_id is now str (was int) on history-fetch endpoints.

Response fields removed: GetAccountResponse.date_time_preferences, GetWebhook.channel, GetProcessResponseInfo.export.

Shape collapses:

  • SendTransacSmsTag is now Union[str, List[str]] (was a pydantic model).
  • GetExtendedCampaignStats.links_stats is now Dict[str, int] (was a pydantic class).
  • ConversationsMessageAttachmentsItem: file_name → name, inline_id → link.

Top-level imports removed (21 names) from from brevo import .... Most notably:

  • CreateBatchEventsRequestItem* (6 names)
  • GetWebhookChannel
  • GetAccountResponseDateTimePreferences
  • GetExtendedCampaignStatsLinksStats
  • SendTransacSmsTagField
  • UpsertrecordsRequestRecordsItemAssociationsItemZero/One* (8 names)

Added

  • New optional fields and filters across contacts.create_contact, contacts.update_contact, email_campaigns.get_email_campaigns, ecommerce.get_products, and several other endpoints.

Migration from v1.x

Warning: The legacy v1.x SDK (brevo-python < 4.0) will continue to receive critical security updates but no new features. We recommend migrating to v5.x.

View migration guide

Key changes:

  • New client initialization via Brevo(api_key="...")
  • Native async support with AsyncBrevo
  • Pydantic-based typed models
  • Automatic retries with exponential backoff
  • httpx replaces urllib3

v1.x:

import brevo_python
from brevo_python.rest import ApiException

configuration = brevo_python.Configuration()
configuration.api_key['api-key'] = 'YOUR_API_KEY'
api_instance = brevo_python.AccountApi(brevo_python.ApiClient(configuration))
api_response = api_instance.get_account()

v5.x:

from brevo import Brevo

client = Brevo(api_key="YOUR_API_KEY")
account = client.account.get_your_account_information_plan_and_credits_details()
Area v1.x (brevo_python) v5.x (brevo)
Module import brevo_python from brevo import Brevo
Client AccountApi(ApiClient(config)) Brevo(api_key="...")
Errors ApiException ApiError with .status_code, .body
HTTP urllib3 httpx
Async Not available AsyncBrevo
Retries Not built-in Automatic with exponential backoff
Python 2.7, 3.4+ 3.8+

Usage

Instantiate and use the client with the following:

from brevo import Brevo
from brevo.transactional_emails import (
    SendTransacEmailRequestSender,
    SendTransacEmailRequestToItem,
)

client = Brevo(
    api_key="YOUR_API_KEY",
)
client.transactional_emails.send_transac_email(
    html_content="<html><head></head><body>Your delivery is expected {{params.estimatedArrival}}.Your tracking code: {{params.trackingCode}}</p></body></html>",
    params={
        "trackingCode": "JD01460000300002350000",
        "estimatedArrival": "Tomorrow",
    },
    sender=SendTransacEmailRequestSender(
        email="hello@brevo.com",
        name="Alex from Brevo",
    ),
    subject="Hello from Brevo!",
    to=[
        SendTransacEmailRequestToItem(
            email="johndoe@example.com",
            name="John Doe",
        )
    ],
)

Async Client

The SDK also exports an async client so that you can make non-blocking calls to our API. Note that if you are constructing an Async httpx client class to pass into this client, use httpx.AsyncClient() instead of httpx.Client() (e.g. for the httpx_client parameter of this client).

import asyncio

from brevo import AsyncBrevo
from brevo.transactional_emails import (
    SendTransacEmailRequestSender,
    SendTransacEmailRequestToItem,
)

client = AsyncBrevo(
    api_key="YOUR_API_KEY",
)


async def main() -> None:
    await client.transactional_emails.send_transac_email(
        html_content="<html><head></head><body>Your delivery is expected {{params.estimatedArrival}}.Your tracking code: {{params.trackingCode}}</p></body></html>",
        params={
            "trackingCode": "JD01460000300002350000",
            "estimatedArrival": "Tomorrow",
        },
        sender=SendTransacEmailRequestSender(
            email="hello@brevo.com",
            name="Alex from Brevo",
        ),
        subject="Hello from Brevo!",
        to=[
            SendTransacEmailRequestToItem(
                email="johndoe@example.com",
                name="John Doe",
            )
        ],
    )


asyncio.run(main())

Exception Handling

When the API returns a non-success status code (4xx or 5xx response), a subclass of the following error will be thrown.

from brevo.core.api_error import ApiError

try:
    client.transactional_emails.send_transac_email(...)
except ApiError as e:
    print(e.status_code)
    print(e.body)

Advanced

Access Raw Response Data

The SDK provides access to raw response data, including headers, through the .with_raw_response property. The .with_raw_response property returns a "raw" client that can be used to access the .headers and .data attributes.

from brevo import Brevo

client = Brevo(
    ...,
)
response = client.transactional_emails.with_raw_response.send_transac_email(...)
print(response.headers)  # access the response headers
print(response.status_code)  # access the response status code
print(response.data)  # access the underlying object

Retries

The SDK is instrumented with automatic retries with exponential backoff. A request will be retried as long as the request is deemed retryable and the number of retry attempts has not grown larger than the configured retry limit (default: 2).

A request is deemed retryable when any of the following HTTP status codes is returned:

  • 408 (Timeout)
  • 429 (Too Many Requests)
  • 5XX (Internal Server Errors)

Use the max_retries request option to configure this behavior.

client.transactional_emails.send_transac_email(..., request_options={
    "max_retries": 1
})

Timeouts

The SDK defaults to a 60 second timeout. You can configure this with a timeout option at the client or request level.

from brevo import Brevo

client = Brevo(
    ...,
    timeout=20.0,
)


# Override timeout for a specific method
client.transactional_emails.send_transac_email(..., request_options={
    "timeout_in_seconds": 1
})

Custom Client

You can override the httpx client to customize it for your use-case. Some common use-cases include support for proxies and transports.

import httpx
from brevo import Brevo

client = Brevo(
    ...,
    httpx_client=httpx.Client(
        proxy="http://my.test.proxy.example.com",
        transport=httpx.HTTPTransport(local_address="0.0.0.0"),
    ),
)

Logging

The SDK has a built-in, opt-in logger. Pass a LogConfig dict (or a pre-built Logger) via the logging constructor option on either Brevo or AsyncBrevo.

Note: The SDK is silent by default (silent=True). Nothing is logged unless you set silent=False. This keeps integration changes from accidentally producing log volume in production.

from brevo import Brevo
from brevo.core.logging import ConsoleLogger

client = Brevo(
    api_key="YOUR_API_KEY",
    logging={
        "level": "debug",          # "debug" | "info" | "warn" | "error"
        "logger": ConsoleLogger(), # built-in; writes to stdlib logging under the "fern" logger
        "silent": False,           # required to actually emit logs
    },
)

LogConfig fields

Field Type Default Description
level "debug" | "info" | "warn" | "error" "info" Minimum level forwarded to the logger
logger ILogger ConsoleLogger() Logger implementation — any object conforming to the ILogger protocol
silent bool True When True, all logging is suppressed regardless of level

Custom logger

Implement the ILogger protocol (debug, info, warn, error methods) to forward to any logging library — stdlib logging, structlog, loguru, or your own sink.

import logging
from brevo import Brevo
from brevo.core.logging import ILogger

logging.basicConfig(level=logging.DEBUG)

class StdlibLogger(ILogger):
    def __init__(self, name: str = "brevo") -> None:
        self._log = logging.getLogger(name)

    def debug(self, message, **kwargs): self._log.debug(message, extra=kwargs)
    def info(self,  message, **kwargs): self._log.info(message,  extra=kwargs)
    def warn(self,  message, **kwargs): self._log.warning(message, extra=kwargs)
    def error(self, message, **kwargs): self._log.error(message, extra=kwargs)

client = Brevo(
    api_key="YOUR_API_KEY",
    logging={"level": "debug", "logger": StdlibLogger(), "silent": False},
)

The default ConsoleLogger uses Python's stdlib logging module under the logger name "fern". If you only need to filter or reformat output, configuring that logger via logging.getLogger("fern") may be enough — you don't always need a custom ILogger.

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

2 maintainers

PyPI data
Data sourced directly from PyPI's database.
Avatar for mourraille from gravatar.com mourraille Avatar for mukulsib from gravatar.com mukulsib

Requires

Python <4.0, >=3.8

Tags

api sdk client brevo sendinblue transactional email sms marketing automation

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

brevo_python-5.0.2.tar.gz (505.2 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

brevo_python-5.0.2-py3-none-any.whl (987.0 kB view details)

Uploaded Python 3

File details

Details for the file brevo_python-5.0.2.tar.gz.

File metadata

  • Download URL: brevo_python-5.0.2.tar.gz
  • Upload date:
  • Size: 505.2 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.5.1 CPython/3.9.25 Linux/6.17.0-1020-azure

File hashes

Hashes for brevo_python-5.0.2.tar.gz
Algorithm Hash digest
SHA256 e317dd78bba01210123dc46d94efb1faf3635f9d58e88fec350c8e33caa75279
MD5 a1c9106534e7461152d14af531519fc9
BLAKE2b-256 a74d8abc86995ddf4a171e750dd83d8e088fb96e39ca62dfbe156bf25f8fd9a8

See more details on using hashes here.

File details

Details for the file brevo_python-5.0.2-py3-none-any.whl.

File metadata

  • Download URL: brevo_python-5.0.2-py3-none-any.whl
  • Upload date:
  • Size: 987.0 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.5.1 CPython/3.9.25 Linux/6.17.0-1020-azure

File hashes

Hashes for brevo_python-5.0.2-py3-none-any.whl
Algorithm Hash digest
SHA256 4addd8cfb8e685c9a339643c5d1c79cd420407c85f1b925b3b539f20b0836d67
MD5 5b6982c8456e1566ba7baec9893ccd38
BLAKE2b-256 c5660ba00fd43ca4ae929b43f0a74de445f49aa9dcbb64f7b669ed9cb2a8bc4d

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page