Brevo Python SDK

Website · API Reference · Support

Official SDK for the Brevo API.

Table of Contents

• Documentation
• Installation
• Reference
• Upgrading from v4.x
• Migration from v1.x
• Usage
• Async Client
• Exception Handling
• Advanced
  • Access Raw Response Data
  • Retries
  • Timeouts
  • Custom Client
  • Logging

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"

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

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

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.

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()

from brevo import Brevo

client = Brevo(api_key="YOUR_API_KEY")
account = client.account.get_your_account_information_plan_and_credits_details()

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

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.