Python SDK | Brevo API Documentation

Overview

The Brevo Python SDK (brevo-python) is a fully typed client library for the Brevo API. It provides:

A unified Brevo client with namespaced service clients
Native async support via AsyncBrevo
Pydantic-based typed models with full type annotations
Automatic retries with exponential backoff
Raw response access with headers and status codes
Custom httpx client support for proxies and mTLS

Version 5.0 introduces breaking changes versus v4.x. v4.x remains supported and continues to receive wire-compatibility fixes — see the changelog for the list of changes and the README for migration steps.

Requirements

Python 3.8+
httpx >= 0.21.2
pydantic >= 1.9.2
typing_extensions >= 4.0.0

Installation

$ pip install brevo-python

Quick start

Initialize the client and send your first email:

quick_start.py

1 from brevo import Brevo
2 from brevo.transactional_emails import (
3     SendTransacEmailRequestSender,
4     SendTransacEmailRequestToItem,
5 )
6 
7 client = Brevo(api_key="your-api-key")
8 
9 result = client.transactional_emails.send_transac_email(
10     subject="Hello from Brevo!",
11     html_content="<html><body><p>Hello,</p><p>This is my first transactional email.</p></body></html>",
12     sender=SendTransacEmailRequestSender(
13         name="Alex from Brevo",
14         email="hello@brevo.com",
15     ),
16     to=[
17         SendTransacEmailRequestToItem(
18             email="johndoe@example.com",
19             name="John Doe",
20         )
21     ],
22 )
23 
24 print("Email sent. Message ID:", result.message_id)

Configuration

Pass keyword arguments to the constructor to configure the client:

configuration.py

1 from brevo import Brevo
2 
3 client = Brevo(
4     api_key="your-api-key",
5     timeout=30.0,
6 )

Constructor parameters

Parameter	Type	Default	Description
`api_key`	`str`	Required	Your Brevo API key
`timeout`	`float`	`60.0`	Default request timeout in seconds
`base_url`	`str`	`None`	Override the default API base URL
`follow_redirects`	`bool`	`True`	Follow HTTP redirects
`httpx_client`	`httpx.Client`	`None`	Custom httpx client instance
`headers`	`dict`	`None`	Additional default headers sent with every request
`logging`	`LogConfig \| Logger`	`None`	Logging configuration (see Logging)

Async client

Use AsyncBrevo for non-blocking calls. Pass httpx.AsyncClient instead of httpx.Client when providing a custom HTTP client:

async_client.py

1 import asyncio
2 from brevo import AsyncBrevo
3 from brevo.transactional_emails import (
4     SendTransacEmailRequestSender,
5     SendTransacEmailRequestToItem,
6 )
7 
8 client = AsyncBrevo(api_key="your-api-key")
9 
10 async def main() -> None:
11     result = await client.transactional_emails.send_transac_email(
12         subject="Hello from Brevo!",
13         html_content="<html><body><p>Hello!</p></body></html>",
14         sender=SendTransacEmailRequestSender(
15             name="Alex from Brevo",
16             email="hello@brevo.com",
17         ),
18         to=[
19             SendTransacEmailRequestToItem(
20                 email="johndoe@example.com",
21                 name="John Doe",
22             )
23         ],
24     )
25     print("Email sent. Message ID:", result.message_id)
26 
27 asyncio.run(main())

Error handling

The SDK raises ApiError (or a typed subclass) for non-2xx HTTP responses:

error_handling.py

1 from brevo import Brevo
2 from brevo.core.api_error import ApiError
3 
4 client = Brevo(api_key="your-api-key")
5 
6 try:
7     client.transactional_emails.send_transac_email(...)
8 except ApiError as e:
9     print(e.status_code)
10     print(e.body)

Error classes

Status code	Class
`400`	`BadRequestError`
`401`	`UnauthorizedError`
`402`	`PaymentRequiredError`
`403`	`ForbiddenError`
`404`	`NotFoundError`
`405`	`MethodNotAllowedError`
`409`	`ConflictError`
`412`	`PreconditionFailedError`
`415`	`UnsupportedMediaTypeError`
`422`	`UnprocessableEntityError`
`424`	`FailedDependencyError`
`429`	`TooManyRequestsError`
`500`	`InternalServerError`

All ApiError instances expose:

status_code — HTTP status code
body — Parsed response body
headers — Response headers

Retries

Automatic retries with exponential backoff are enabled by default (2 retries). Configure at the client or request level:

retries.py

1 from brevo import Brevo
2 
3 # Client-level (not directly supported — use request_options per request)
4 client = Brevo(api_key="your-api-key")
5 
6 # Request-level
7 client.transactional_emails.send_transac_email(
8     ...,
9     request_options={"max_retries": 3},
10 )

Retry behavior

Retryable status codes: 408, 429, 5xx
Backoff: Exponential with jitter
Disable: Set max_retries: 0 in request_options

Timeouts

Default timeout is 60 seconds. Configure at the client or request level:

timeouts.py

1 from brevo import Brevo
2 
3 # Client-level
4 client = Brevo(
5     api_key="your-api-key",
6     timeout=30.0,
7 )
8 
9 # Request-level
10 client.transactional_emails.send_transac_email(
11     ...,
12     request_options={"timeout_in_seconds": 10},
13 )

Recommended timeout values

Use case	Timeout
Standard API calls	`30–60s` (default)
Quick operations	`10–15s`
Bulk operations	`120–300s`
Real-time / low-latency	`5–10s`

Request options

All service methods accept a request_options dict as the final keyword argument:

Option	Type	Description
`timeout_in_seconds`	`int`	Override timeout for this request
`max_retries`	`int`	Override max retries for this request
`additional_headers`	`dict`	Merge additional headers into the request
`additional_query_parameters`	`dict`	Add query parameters to the request
`additional_body_parameters`	`dict`	Add body parameters to the request

request_options.py

1 client.transactional_emails.send_transac_email(
2     ...,
3     request_options={
4         "timeout_in_seconds": 10,
5         "max_retries": 1,
6         "additional_headers": {"X-Custom-Header": "custom-value"},
7     },
8 )

Raw response access

Access response headers and status code via .with_raw_response:

raw_response.py

1 from brevo import Brevo
2 
3 client = Brevo(api_key="your-api-key")
4 
5 response = client.transactional_emails.with_raw_response.send_transac_email(...)
6 
7 print(response.status_code)
8 print(response.headers)
9 print(response.data)

Logging

The SDK has a built-in, opt-in logger you can plug your own implementation into. Pass a LogConfig dict (or a pre-built Logger) via the logging constructor option.

By default the SDK is silent: nothing is logged unless you set silent=False. This keeps integration changes from accidentally producing log volume in production.

logging_basic.py

1 from brevo import Brevo
2 from brevo.core.logging import ConsoleLogger
3 
4 client = Brevo(
5     api_key="your-api-key",
6     logging={
7         "level": "debug",          # "debug" | "info" | "warn" | "error"
8         "logger": ConsoleLogger(), # built-in; writes to stdlib `logging` under the "fern" logger
9         "silent": False,           # required to actually emit logs
10     },
11 )

`LogConfig` fields

Field	Type	Default	Description
`level`	`"debug" \| "info" \| "warn" \| "error"`	`"info"`	Minimum level that gets 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 (a typing.Protocol with debug, info, warn, error methods) to forward to any logging library — Python’s stdlib logging, structlog, loguru, or your own sink.

custom_logger.py

1 import logging
2 from brevo import Brevo
3 from brevo.core.logging import ILogger
4 
5 logging.basicConfig(level=logging.DEBUG)
6 
7 class StdlibLogger(ILogger):
8     def __init__(self, name: str = "brevo") -> None:
9         self._log = logging.getLogger(name)
10 
11     def debug(self, message: str, **kwargs) -> None: self._log.debug(message, extra=kwargs)
12     def info(self,  message: str, **kwargs) -> None: self._log.info(message,  extra=kwargs)
13     def warn(self,  message: str, **kwargs) -> None: self._log.warning(message, extra=kwargs)
14     def error(self, message: str, **kwargs) -> None: self._log.error(message, extra=kwargs)
15 
16 client = Brevo(
17     api_key="your-api-key",
18     logging={"level": "debug", "logger": StdlibLogger(), "silent": False},
19 )

Integrations

structlog

1 import structlog
2 from brevo import Brevo
3 from brevo.core.logging import ILogger
4 
5 class StructlogLogger(ILogger):
6     def __init__(self) -> None:
7         self._log = structlog.get_logger("brevo")
8 
9     def debug(self, message, **kwargs): self._log.debug(message, **kwargs)
10     def info(self,  message, **kwargs): self._log.info(message,  **kwargs)
11     def warn(self,  message, **kwargs): self._log.warning(message, **kwargs)
12     def error(self, message, **kwargs): self._log.error(message, **kwargs)
13 
14 client = Brevo(
15     api_key="your-api-key",
16     logging={"level": "info", "logger": StructlogLogger(), "silent": False},
17 )

loguru

1 from loguru import logger
2 from brevo import Brevo
3 from brevo.core.logging import ILogger
4 
5 class LoguruLogger(ILogger):
6     def debug(self, message, **kwargs): logger.bind(**kwargs).debug(message)
7     def info(self,  message, **kwargs): logger.bind(**kwargs).info(message)
8     def warn(self,  message, **kwargs): logger.bind(**kwargs).warning(message)
9     def error(self, message, **kwargs): logger.bind(**kwargs).error(message)
10 
11 client = Brevo(
12     api_key="your-api-key",
13     logging={"level": "debug", "logger": LoguruLogger(), "silent": False},
14 )

Reusing a pre-built Logger

Build a Logger once and reuse it across Brevo and AsyncBrevo instances:

1 from brevo import Brevo, AsyncBrevo
2 from brevo.core.logging import Logger, ConsoleLogger
3 
4 shared = Logger(level="info", logger=ConsoleLogger(), silent=False)
5 
6 sync_client  = Brevo(api_key="your-api-key", logging=shared)
7 async_client = AsyncBrevo(api_key="your-api-key", logging=shared)

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.

Custom HTTP client

Override the default httpx client for proxies, custom transports, or mTLS:

custom_http_client.py

1 import httpx
2 from brevo import Brevo
3 
4 client = Brevo(
5     api_key="your-api-key",
6     httpx_client=httpx.Client(
7         proxy="http://my.test.proxy.example.com",
8         transport=httpx.HTTPTransport(local_address="0.0.0.0"),
9     ),
10 )

Common integrations

Async with custom client

1 import httpx
2 from brevo import AsyncBrevo
3 
4 client = AsyncBrevo(
5     api_key="your-api-key",
6     httpx_client=httpx.AsyncClient(
7         proxy="http://my.test.proxy.example.com",
8     ),
9 )

Custom timeout and transport

1 import httpx
2 from brevo import Brevo
3 
4 client = Brevo(
5     api_key="your-api-key",
6     httpx_client=httpx.Client(
7         timeout=httpx.Timeout(120.0, connect=10.0),
8         transport=httpx.HTTPTransport(retries=3),
9     ),
10 )

With event hooks

1 import httpx
2 from brevo import Brevo
3 
4 def log_request(request: httpx.Request) -> None:
5     print(f"→ {request.method} {request.url}")
6 
7 def log_response(response: httpx.Response) -> None:
8     print(f"← {response.status_code}")
9 
10 client = Brevo(
11     api_key="your-api-key",
12     httpx_client=httpx.Client(
13         event_hooks={"request": [log_request], "response": [log_response]},
14     ),
15 )

Available services

The Brevo and AsyncBrevo clients expose the following service namespaces:

Property	Description
`transactional_emails`	Send emails, manage templates, blocked contacts and domains
`transactional_sms`	Send SMS messages and view delivery statistics
`transactional_whats_app`	Send WhatsApp messages and view event reports
`sms_templates`	Manage SMS templates
`contacts`	Manage contacts, lists, folders, attributes and segments
`email_campaigns`	Create and manage email marketing campaigns
`sms_campaigns`	Create and manage SMS marketing campaigns
`whats_app_campaigns`	Create and manage WhatsApp campaigns and templates
`companies`	Manage CRM companies
`deals`	Manage CRM deals and pipelines
`tasks`	Manage CRM tasks
`notes`	Manage CRM notes
`files`	Upload and manage CRM files
`conversations`	Manage conversation messages and automated messages
`ecommerce`	Manage products, categories, orders and attribution
`coupons`	Manage coupon collections and coupons
`payments`	Create and manage payment requests
`event`	Track custom events
`webhooks`	Manage webhooks
`senders`	Manage senders and IPs
`domains`	Manage and authenticate domains
`account`	Retrieve account information and activity logs
`inbound_parsing`	Retrieve inbound email events and attachments
`custom_objects`	Manage custom object records
`external_feeds`	Manage external RSS feeds
`master_account`	Manage sub-accounts and groups (enterprise)
`user`	Manage users and permissions
`process`	Retrieve background process status
`program`	Manage loyalty programs
`balance`	Manage loyalty balances and transactions
`reward`	Manage loyalty rewards and vouchers
`tier`	Manage loyalty tiers and tier groups

Migration from v1.x

Key changes

Area	v1.x (`brevo_python`)	v4.x (`brevo`)
Module	`import brevo_python`	`from brevo import Brevo`
Client	`AccountApi(ApiClient(config))`	`Brevo(api_key="...")`
Config	`Configuration()` + `api_key['api-key']`	Constructor parameter `api_key`
Errors	`ApiException`	`ApiError` with `.status_code`, `.body`
HTTP	`urllib3`	`httpx`
Async	Not available	`AsyncBrevo`
Retries	Not built-in	Automatic with exponential backoff
Timeouts	Manual	60s default, configurable
Python	2.7, 3.4+	3.8+

Migration example

1 # v1.x
2 import brevo_python
3 from brevo_python.rest import ApiException
4 
5 configuration = brevo_python.Configuration()
6 configuration.api_key['api-key'] = 'YOUR_API_KEY'
7 
8 api_instance = brevo_python.AccountApi(
9     brevo_python.ApiClient(configuration)
10 )
11 account = api_instance.get_account()