PHP SDK | Brevo API Documentation

Overview

The Brevo PHP SDK (getbrevo/brevo-php) is a type-safe client library for the Brevo API. It provides:

A unified Brevo client with namespaced service clients
Strongly typed request and response objects with full PHPDoc annotations
PSR-18 HTTP client compatibility (Guzzle, Symfony HttpClient, etc.)
Automatic retries with exponential backoff
Structured error handling via BrevoApiException

Version 4.0 is a full rewrite and is not backwards compatible with the legacy SDK. The legacy SDK will continue to receive critical security updates but no new features. We recommend migrating to v4.x for new and existing projects.

Requirements

PHP 8.1+
ext-json
A PSR-18 HTTP client (e.g., Guzzle, Symfony HttpClient)

Installation

Install the SDK using Composer:

$ composer require getbrevo/brevo-php

Guzzle is recommended as the HTTP client:

$ composer require getbrevo/brevo-php guzzlehttp/guzzle

If no HTTP client is provided, the SDK uses php-http/discovery to auto-detect an installed PSR-18 client.

Quick start

Initialize the client and send your first email:

quick_start.php

1 <?php
2 
3 require_once __DIR__ . '/vendor/autoload.php';
4 
5 use Brevo\Brevo;
6 use Brevo\TransactionalEmails\Requests\SendTransacEmailRequest;
7 use Brevo\TransactionalEmails\Types\SendTransacEmailRequestSender;
8 use Brevo\TransactionalEmails\Types\SendTransacEmailRequestToItem;
9 
10 $client = new Brevo(apiKey: 'your-api-key');
11 
12 $result = $client->transactionalEmails->sendTransacEmail(
13     new SendTransacEmailRequest([
14         'subject' => 'Hello from Brevo!',
15         'htmlContent' => '<html><body><p>Hello,</p><p>This is my first transactional email.</p></body></html>',
16         'sender' => new SendTransacEmailRequestSender([
17             'name' => 'Alex from Brevo',
18             'email' => 'hello@brevo.com',
19         ]),
20         'to' => [
21             new SendTransacEmailRequestToItem([
22                 'email' => 'johndoe@example.com',
23                 'name' => 'John Doe',
24             ]),
25         ],
26     ])
27 );
28 
29 echo 'Email sent. Message ID: ' . $result->messageId . PHP_EOL;

Configuration

Pass an options array as the second argument to configure the client:

configuration.php

1 $client = new Brevo('your-api-key', [
2     'timeout'    => 30,  // seconds
3     'maxRetries' => 3,
4 ]);

Constructor parameters

Parameter	Type	Default	Description
`apiKey`	`string`	Required	Your Brevo API key
`timeout`	`float`	`null`	Request timeout in seconds. Defaults to the underlying HTTP client’s default.
`baseUrl`	`string`	`null`	Override the default API base URL
`maxRetries`	`int`	`2`	Maximum retry attempts on retryable errors
`client`	`ClientInterface`	`null`	Custom PSR-18 HTTP client
`headers`	`array<string, string>`	`null`	Additional default headers sent with every request

Error handling

BrevoApiException is thrown for any non-2xx HTTP response. Catch it to inspect the status code and response body:

error_handling.php

1 use Brevo\Exceptions\BrevoApiException;
2 use Brevo\Exceptions\BrevoException;
3 
4 try {
5     $client->transactionalEmails->sendTransacEmail($request);
6 } catch (BrevoApiException $e) {
7     $statusCode = $e->getCode();
8     $body       = $e->getBody();
9 
10     if ($statusCode === 401) {
11         echo 'Invalid API key';
12     } elseif ($statusCode === 429) {
13         echo 'Rate limited. Check Retry-After header.';
14     } else {
15         echo "API error {$statusCode}: " . $e->getMessage();
16     }
17 } catch (BrevoException $e) {
18     echo 'SDK error: ' . $e->getMessage();
19 }

Exception classes

Class	Description
`BrevoApiException`	Thrown for non-2xx HTTP responses
`BrevoException`	Base class for all SDK-level errors

BrevoApiException exposes:

getCode() — HTTP status code
getMessage() — Error message
getBody() — Parsed response body

Status codes

Code	Meaning
`400`	Bad Request
`401`	Unauthorized
`403`	Forbidden
`404`	Not Found
`422`	Unprocessable Entity
`429`	Too Many Requests
`5xx`	Server Error

Retries

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

retries.php

1 // Client-level
2 $client = new Brevo('your-api-key', [
3     'maxRetries' => 3,
4 ]);
5 
6 // Request-level (overrides client setting)
7 $client->transactionalEmails->sendTransacEmail($request, [
8     'maxRetries' => 0, // Disable retries for this request
9 ]);

Retry behavior

Retryable status codes: 408, 429, 5xx
Backoff schedule: ~1s, ~2s, ~4s (exponential, base 1000ms) with ±10% symmetric jitter
Maximum delay: 60s per retry interval
Rate limit headers: Respects Retry-After and X-RateLimit-Reset response headers

Timeouts

No default timeout is configured. Unless you set one, the underlying HTTP client’s default applies (Guzzle defaults to no timeout). Set an explicit timeout at the client or request level:

timeouts.php

1 // Client-level
2 $client = new Brevo('your-api-key', [
3     'timeout' => 30,
4 ]);
5 
6 // Request-level (overrides client setting)
7 $client->transactionalEmails->sendTransacEmail($request, [
8     'timeout' => 10,
9 ]);

Timeout forwarding is supported for Guzzle and Symfony HttpClient. For other PSR-18 clients, the timeout value is ignored and a PHP warning is triggered.

Recommended timeout values

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

Request options

Both timeout, maxRetries, and headers can be overridden per request by passing an options array as the last argument:

request_options.php

1 $client->transactionalEmails->sendTransacEmail($request, [
2     'timeout'    => 10,
3     'maxRetries' => 1,
4     'headers'    => [
5         'X-Custom-Header' => 'custom-value',
6     ],
7 ]);

Query parameters

Pass query parameters via the typed request object:

query_params.php

1 use Brevo\Contacts\Requests\GetContactsRequest;
2 
3 $client->contacts->getContacts(new GetContactsRequest([
4     'limit'  => 50,
5     'offset' => 0,
6 ]));

Binary responses

Some endpoints (e.g., attachment downloads) return binary content directly:

binary_response.php

1 $content = $client->inboundParsing->getInboundEmailAttachment($downloadToken);
2 
3 file_put_contents('path/to/file', $content);

Type safety

All request and response objects are strongly typed. Use the generated request classes for IDE autocomplete and static analysis:

type_safety.php

1 use Brevo\TransactionalEmails\Requests\SendTransacEmailRequest;
2 use Brevo\TransactionalEmails\Types\SendTransacEmailRequestSender;
3 use Brevo\TransactionalEmails\Types\SendTransacEmailRequestToItem;
4 
5 $request = new SendTransacEmailRequest([
6     'subject'     => 'First email',
7     'textContent' => 'Hello world!',
8     'sender'      => new SendTransacEmailRequestSender([
9         'name'  => 'Bob Wilson',
10         'email' => 'bob.wilson@brevo.com',
11     ]),
12     'to' => [
13         new SendTransacEmailRequestToItem([
14             'email' => 'sarah.davis@example.com',
15             'name'  => 'Sarah Davis',
16         ]),
17     ],
18 ]);

Custom HTTP client

Pass any PSR-18-compatible client via the client option:

custom_http_client.php

1 use Brevo\Brevo;
2 use GuzzleHttp\Client;
3 
4 $client = new Brevo('your-api-key', [
5     'client' => new Client(['timeout' => 5.0]),
6 ]);

Common integrations

Guzzle

1 use GuzzleHttp\Client;
2 
3 $client = new Brevo('your-api-key', [
4     'client' => new Client(['timeout' => 5.0]),
5 ]);

Symfony HttpClient

1 use Symfony\Component\HttpClient\Psr18Client;
2 use Symfony\Component\HttpClient\HttpClient;
3 
4 $client = new Brevo('your-api-key', [
5     'client' => new Psr18Client(
6         HttpClient::create(['timeout' => 5.0])
7     ),
8 ]);

Laravel

1 // AppServiceProvider.php
2 use Brevo\Brevo;
3 
4 public function register(): void
5 {
6     $this->app->singleton(Brevo::class, function () {
7         return new Brevo(apiKey: config('services.brevo.api_key'));
8     });
9 }

PHP-specific considerations

API key from environment

Avoid hardcoding API keys. Use environment variables:

env_api_key.php

1 $client = new Brevo(apiKey: $_ENV['BREVO_API_KEY'] ?? getenv('BREVO_API_KEY'));

In Laravel, use config('services.brevo.api_key'). In Symfony, use $_ENV['BREVO_API_KEY'] or service parameters.

Memory limits

For large operations (bulk exports, large attachments), adjust PHP’s memory_limit:

1 ini_set('memory_limit', '256M');

Available services

The unified Brevo client exposes the following service namespaces:

Property	Description
`transactionalEmails`	Send emails, manage templates, blocked contacts and domains
`transactionalSms`	Send SMS messages and view delivery statistics
`transactionalWhatsApp`	Send WhatsApp messages and view event reports
`smsTemplates`	Manage SMS templates
`contacts`	Manage contacts, lists, folders, attributes and segments
`emailCampaigns`	Create and manage email marketing campaigns
`smsCampaigns`	Create and manage SMS marketing campaigns
`whatsAppCampaigns`	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
`inboundParsing`	Retrieve inbound email events and attachments
`customObjects`	Manage custom object records
`externalFeeds`	Manage external RSS feeds
`masterAccount`	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 the legacy SDK

Key changes

Area	Legacy SDK	v4.x
Import	`use Brevo\Client\Api\*`	`use Brevo\Brevo`
Client init	`new TransactionalEmailsApi($httpClient, $config)`	`new Brevo(apiKey: 'api-key')`
Config	`Configuration::getDefaultConfiguration()`	Constructor options array
Requests	Setter methods (`->setSubject(...)`)	Typed request objects
Errors	Guzzle exceptions	`BrevoApiException` with `getCode()`, `getBody()`
HTTP client	Hard Guzzle dependency	PSR-18 (any compatible client)
Retries	Not built-in	Automatic with exponential backoff
PHP	7.x+	8.1+

Migration example

1 // Legacy SDK
2 use Brevo\Client\Configuration;
3 use Brevo\Client\Api\TransactionalEmailsApi;
4 use Brevo\Client\Model\SendSmtpEmail;
5 
6 $config = Configuration::getDefaultConfiguration()
7     ->setApiKey('api-key', 'xkeysib-xxx');
8 
9 $api = new TransactionalEmailsApi(new \GuzzleHttp\Client(), $config);
10 
11 $message = new SendSmtpEmail();
12 $message->setSubject('First email');
13 $message->setTextContent('Hello world!');
14 $message->setSender(['name' => 'Bob Wilson', 'email' => 'bob.wilson@brevo.com']);
15 $message->setTo([['email' => 'sarah.davis@example.com', 'name' => 'Sarah Davis']]);
16 
17 $api->sendTransacEmail($message);