> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.brevo.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.brevo.com/_mcp/server.

# Key concepts

## Overview

The Brevo API uses REST over HTTPS. All requests require authentication via an API key, and responses are returned as JSON. This guide covers the essentials before your first API call.

## Base URL and versioning

All API requests use the base URL with version v3:

```http
https://api.brevo.com/v3/
```

## Authentication

Include your API key in the `api-key` header for every request. Generate an API key from your [Brevo account settings](https://app.brevo.com/settings/keys/api).

See the [authentication guide](/docs/api-key-authentication) for setup instructions.

## Making requests

### Required headers

Every request must include:

* `content-type: application/json` - Specifies JSON payload format
* `api-key: YOUR_API_KEY` - Your authentication token

### Request methods

The API supports standard HTTP methods:

* `GET` - Retrieve resources
* `POST` - Create resources
* `PUT` - Update resources
* `DELETE` - Remove resources

### Example request

Create a contact using the API:

#### cURL

```bash
curl -X POST 'https://api.brevo.com/v3/contacts' \
     -H 'content-type: application/json' \
     -H 'api-key: YOUR_API_KEY' \
     -d '{"email":"contact@example.com"}'
```

#### Python

```python
import sib_api_v3_sdk
from sib_api_v3_sdk.rest import ApiException

configuration = sib_api_v3_sdk.Configuration()
configuration.api_key['api-key'] = 'YOUR_API_KEY'

api_instance = sib_api_v3_sdk.ContactsApi(
    sib_api_v3_sdk.ApiClient(configuration)
)
create_contact = sib_api_v3_sdk.CreateContact(
    email="contact@example.com"
)

try:
    api_response = api_instance.create_contact(create_contact)
    print(api_response)
except ApiException as e:
    print(f"Exception: {e}")
```

#### Node.js

```javascript
const SibApiV3Sdk = require('sib-api-v3-sdk');

const defaultClient = SibApiV3Sdk.ApiClient.instance;
const apiKey = defaultClient.authentications['api-key'];
apiKey.apiKey = 'YOUR_API_KEY';

const apiInstance = new SibApiV3Sdk.ContactsApi();
const createContact = { email: "contact@example.com" };

apiInstance.createContact(createContact)
  .then(data => console.log('Success:', data))
  .catch(error => console.error('Error:', error));
```

#### PHP

```php
require_once(__DIR__ . '/vendor/autoload.php');

$config = SendinBlue\Client\Configuration::getDefaultConfiguration();
$config->setApiKey('api-key', 'YOUR_API_KEY');

$apiInstance = new SendinBlue\Client\Api\ContactsApi(
    new GuzzleHttp\Client(),
    $config
);

$createContact = new \SendinBlue\Client\Model\CreateContact();
$createContact['email'] = 'contact@example.com';

try {
    $result = $apiInstance->createContact($createContact);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception: ' . $e->getMessage();
}
```

We provide official SDKs for Python, Node.js, PHP, Ruby, Java, TypeScript, Go, and C#. See [supported programming languages](/docs/api-clients) for installation instructions.

## Responses

### Response format

Responses are returned as JSON objects. Some operations return empty responses with HTTP status codes (for example, `204 No Content` for successful deletions).

### Success response

Successful requests return data specific to the endpoint:

```json
{
  "id": 123,
  "email": "contact@example.com",
  "attributes": {
    "FIRSTNAME": "John",
    "LASTNAME": "Doe"
  }
}
```

### Error response

Errors include a `code` and `message`:

```json
{
  "code": "invalid_parameter",
  "message": "Invalid email address"
}
```

## HTTP status codes

| Code | Status             | Description                                              |
| :--- | :----------------- | :------------------------------------------------------- |
| 200  | OK                 | Request succeeded                                        |
| 201  | Created            | Resource created successfully                            |
| 202  | Accepted           | Request accepted for processing                          |
| 204  | No Content         | Resource updated or deleted successfully                 |
| 400  | Bad Request        | Invalid request. Check error details in response body    |
| 401  | Unauthorized       | Invalid or missing API key                               |
| 402  | Payment Required   | Account requires activation or additional credits        |
| 403  | Forbidden          | Insufficient permissions for this resource               |
| 404  | Not Found          | Endpoint or resource does not exist                      |
| 405  | Method Not Allowed | HTTP method not supported for this endpoint              |
| 406  | Not Acceptable     | Content-Type must be `application/json`                  |
| 429  | Too Many Requests  | Rate limit exceeded. See [rate limits](/docs/api-limits) |

## Error codes

Error responses include specific codes in the JSON body:

| Code                       | Description                                       |
| :------------------------- | :------------------------------------------------ |
| `invalid_parameter`        | Parameter value is invalid. Check format and type |
| `missing_parameter`        | Required parameter is missing                     |
| `out_of_range`             | Parameter value outside allowed range             |
| `unauthorized`             | Authentication failed or insufficient permissions |
| `document_not_found`       | Resource specified in path does not exist         |
| `method_not_allowed`       | HTTP method not allowed for this endpoint         |
| `not_enough_credits`       | Insufficient credits to complete the request      |
| `duplicate_parameter`      | Parameter value already exists                    |
| `duplicate_request`        | Identical request submitted too frequently        |
| `account_under_validation` | Account is pending validation                     |
| `permission_denied`        | Account lacks permission for this operation       |

## Pagination

Endpoints that return lists support pagination using query parameters:

| Parameter | Type    | Description                                                       |
| :-------- | :------ | :---------------------------------------------------------------- |
| `limit`   | integer | Number of results per page. Default and maximum vary by endpoint  |
| `offset`  | integer | Starting index (0-based). For page 2 with limit 50, use offset=50 |

```bash
curl -X GET "https://api.brevo.com/v3/contacts?limit=50&offset=0" \
     -H "api-key: YOUR_API_KEY" \
     -H "content-type: application/json"
```

## Rate limiting

Rate limits prevent API abuse and ensure service stability. Limits vary by endpoint and account tier.

See the [rate limits documentation](/docs/api-limits) for per-endpoint limits and Enterprise tier details.

When rate limits are exceeded, you receive a `429 Too Many Requests` response with headers indicating:

* `x-sib-ratelimit-limit` - Maximum requests allowed
* `x-sib-ratelimit-remaining` - Requests remaining in current window
* `x-sib-ratelimit-reset` - Time until limit resets

## IP addresses

Some integrations require whitelisting Brevo IP addresses for security or firewall configuration.

View the full list of Brevo IP ranges in our [help center](https://help.brevo.com/hc/en-us/articles/208848409).

Many Brevo services use Cloudflare's proxy. Whitelist [Cloudflare IP ranges](https://www.cloudflare.com/en-gb/ips/) in addition to Brevo IPs.