REST API: Key Concepts

Learn the key concepts on Brevo API

Here is everything you need to understand before starting using the API.


The API is accessed by making HTTPS requests to a specific version endpoint URL, in which GET, POST, PUT, and DELETE methods dictate how your interact with the objects available. Every endpoint is accessed only via the SSL-enabled HTTPS (port 443) protocol.

Every call must contain the version number. The latest version is v3.


Requests must be sent over HTTPS with any payload formatted in JSON (application/json). Every request must include the headers content-type: application/json and api-key.

The API key can be retrieved from the account settings. Make sure to get the key for the version of the API you're using.

curl -X POST ''
     -H 'content-type: application/json'
     -H 'api-key: YOUR_API_KEY'
     -d '{"email":"[email protected]"}'
require_once(__DIR__ . '/vendor/autoload.php');

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

$apiInstance = new SendinBlue\Client\Api\ContactsApi(
    // If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
    // This is optional, `GuzzleHttp\Client` will be used as default.
    new GuzzleHttp\Client(),
$createContact = new \SendinBlue\Client\Model\CreateContact(); // \SendinBlue\Client\Model\CreateContact | Values to create a contact
$createContact['email'] = '[email protected]';
try {
    $result = $apiInstance->createContact($createContact);
} catch (Exception $e) {
    echo 'Exception when calling ContactsApi->createContact: ', $e->getMessage(), PHP_EOL;
// Node.js SDK:
var SibApiV3Sdk = require('sib-api-v3-sdk');
var defaultClient = SibApiV3Sdk.ApiClient.instance;

// Configure API key authorization: api-key
var apiKey = defaultClient.authentications['api-key'];
apiKey.apiKey = 'YOUR API KEY';

var apiInstance = new SibApiV3Sdk.ContactsApi();

var createContact = new SibApiV3Sdk.CreateContact(); // CreateContact | Values to create a contact
createContact = { 'email' : "[email protected]" };

apiInstance.createContact(createContact).then(function(data) {
  console.log('API called successfully. Returned data: ' + data);
}, function(error) {
# Ruby SDK:

# load the gem
require 'sib-api-v3-sdk'
# setup authorization
SibApiV3Sdk.configure do |config|
  # Configure API key authorization: api-key
  config.api_key['api-key'] = 'YOUR API KEY'

api_instance =

create_contact = # CreateContact | Values to create a contact
create_contact = { 'email' => "[email protected]" }

  #Create a contact
  result = api_instance.create_contact(create_contact)
  p result
rescue SibApiV3Sdk::ApiError => e
  puts "Exception when calling ContactsApi->create_contact: #{e}"
# Python SDK:
from __future__ import print_function
import time
import sib_api_v3_sdk
from import ApiException
from pprint import pprint

# Configure API key authorization: api-key
configuration = sib_api_v3_sdk.Configuration()
configuration.api_key['api-key'] = 'YOUR_API_KEY'

# create an instance of the API class
api_instance = sib_api_v3_sdk.ContactsApi(sib_api_v3_sdk.ApiClient(configuration))
create_contact = sib_api_v3_sdk.CreateContact(
  email= "[email protected]", 
) # CreateContact | Values to create a contact

    # Create a contact
    api_response = api_instance.create_contact(create_contact)
except ApiException as e:
    print("Exception when calling ContactsApi->create_contact: %s\n" % e)
// Java SDK:
// Import classes:
//import sendinblue.ApiClient;
//import sendinblue.ApiException;
//import sendinblue.Configuration;
//import sendinblue.auth.*;
//import sibApi.ContactsApi;

ApiClient defaultClient = Configuration.getDefaultApiClient();

// Configure API key authorization: api-key
ApiKeyAuth apiKey = (ApiKeyAuth) defaultClient.getAuthentication("api-key");
apiKey.setApiKey("YOUR API KEY");

ContactsApi apiInstance = new ContactsApi();
CreateContact createContact = new CreateContact(); // CreateContact | Values to create a contact"[email protected]");

try {
    CreateModel result = apiInstance.createContact(createContact);
} catch (ApiException e) {
    System.err.println("Exception when calling ContactsApi#createContact");
// This example is for TypeScript node

var SibApiV3Sdk = require('sib-api-v3-typescript');

var apiInstance = new SibApiV3Sdk.CreateContact();

// Configure API key authorization: api-key

var apiKey = apiInstance.authentications['apiKey'];
apiKey.apiKey = "YOUR API KEY"

// Configure API key authorization: partner-key

var partnerKey = apiInstance.authentications['partnerKey'];
partnerKey.apiKey = "YOUR API KEY"

var createContact = { 'email' : "[email protected]" };

apiInstance.createContact(createContact).then(function(data) {
  console.log('API called successfully. Returned data: ' + data);
}, function(error) {
We also support Go and C#.

Go to our Go SDK documentation:

Go to our C# SDK documentation:

Rate limiting

Our endpoint list has been optimised in such way that we ensure the critical routes can efficiently handle as many requests as possible without compromising stability. You can refer to the limits for each endpoint in this section.


Depending on the endpoint and on your request, the results returned may be paginated. You can page through the results by using following parameters in the query string.

limitintegerThe number of results returned per page. The default and maximum value may vary per API
offsetintegerThe index of the first document in the page (starting with 0). For example, if the limit is 50 and you want to retrieve the page 2, then offset=50
curl -X GET ""
     -H "api-key: xkeysib-xxx"
     -H "content-type: application/json"



Each response can either be empty - for example in case of an update which returns an http 204 response and doesn't need to return additional infos - or a JSON object.

In case of success the JSON object returned for each endpoint is different.

An error object will contain an error code and a human readable description of the error.

  "ips": [
      "id": 3,
      "ip": "",
      "domain": "mailing.myshop.dom"
      "id": 5,
      "ip": "",
      "domain": "newsletter.myshop.dom"
  "code": "invalid_parameter",
  "message": "Invalid email address"

HTTP response codes

Please find below, the HTTP response codes that can be returned by Brevo API:

HTTP codeStatusDescription
200OKThe request was successful
201CreatedThe object was successfully created
202AcceptedThe request was accepted and will be processed
204No contentThe object was successfully updated or deleted
400Bad requestRequest is invalid. Check the error code in JSON
401UnauthorizedYou have not been authenticated. Make sure the provided api-key is correct
402Payment RequiredMake sure you're account is activated and that you've sufficient credits
403ForbiddenYou do not have the rights to access the resource
404Not FoundMake sure your calling an existing endpoint and that the parameters (object id etc.) in the path are correct
405Method Not AllowedThe verb you're using is not allowed for this endpoint. Make sure you're using the correct method (GET, POST, PUT, DELETE)
406Not AcceptableThe value of contentType for PUT or POST request in request headers is not application/json. Make sure the value is application/json only and not empty
429Too Many RequestsThe expected rate limit is exceeded. Refer here

Error codes

Please find bellow the codes returned in the JSON body in case of an error.

invalid_parameterThe value of the parameter you have provided is not valid. Please check the format and the type
missing_parameterOne of the required parameter is missing to perform the request
out_of_rangeThe value of the parameter you have provided is not included in the authorized range
unauthorizedYou are not authorized to do this call
reseller_permission_deniedYou need a reseller plan to perform this API call
document_not_foundThe parameter value in brackets {} is not found
method_not_allowedThe method you are requesting for this path is not allowed. (ex : you are doing put but only get method is allowed for the path
not_enough_creditsYou don't have enough credit to perform the request. Example : you are trying to send a campaign but your plan has expired
duplicate_parameterOne of the parameters in the request already exists.
duplicate_requestThe request rate of the very same request is too high
account_under_validationYour account is under validation
permission_deniedYou don't have the permission to perform this request

Brevo IP addresses

Some applications might find it handy to know about Brevo IPs. This page is intended to be the definitive source of Brevo current IP ranges. We will add new IPs over time.


You can see here all the IP ranges for Brevo.


Cloudflare's IPs

Many of our applications are also taking advantage of Cloudflare's proxy. You will have to whitelist their IPs as well. The exhaustive list of Cloudflare's IPs can be found here.