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 4.0 is a full rewrite and is not backwards compatible with the v1.x SDK. The legacy v1.x SDK (brevo-python < 4.0) will continue to receive critical security updates but no new features. We recommend migrating to v4.x for new and existing projects.

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

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)

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