Key concepts

Overview

The Brevo API uses REST principles over HTTPS. All requests require authentication via an API key, and responses are returned as JSON. This guide covers the essential concepts you need to understand before making your first API call.

Base URL and versioning

All API requests use the base URL with version v3:

1
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.

See the authentication guide for detailed 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 -X POST 'https://api.brevo.com/v3/contacts' \
>
     -H 'content-type: application/json' \
>
     -H 'api-key: YOUR_API_KEY' \
>
     -d '{"email":"contact@example.com"}'

Responses

Response format

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

Success response

Successful requests return data specific to the endpoint:

1
{
2
  "id": 123,
3
  "email": "contact@example.com",
4
  "attributes": {
5
    "FIRSTNAME": "John",
6
    "LASTNAME": "Doe"
7
  }
8
}

Error response

Errors include a code and message:

1
{
2
  "code": "invalid_parameter",
3
  "message": "Invalid email address"
4
}

HTTP status codes

Error codes

Error responses include specific codes in the JSON body:

Pagination

Endpoints that return lists support pagination using query parameters:

$
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.

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.