How the API works

Learn the key concepts on Sendinblue's API

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

Endpoints

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.

https://api.sendinblue.com/v3/

Requests

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 'https://api.sendinblue.com/v3/contacts'
     -H 'content-type: application/json'
     -H 'api-key: YOUR_API_KEY'
     -d '{"email":"john@doe.com"}'
<?php
// PHP SDK: https://github.com/sendinblue/APIv3-php-library
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(),
    $config
);
$createContact = new \SendinBlue\Client\Model\CreateContact(); // \SendinBlue\Client\Model\CreateContact | Values to create a contact
$createContact['email'] = 'john@doe.com';
  
try {
    $result = $apiInstance->createContact($createContact);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling ContactsApi->createContact: ', $e->getMessage(), PHP_EOL;
}
?>
// Node.js SDK: https://github.com/sendinblue/APIv3-nodejs-library
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' : "john@doe.com" };

apiInstance.createContact(createContact).then(function(data) {
  console.log('API called successfully. Returned data: ' + data);
}, function(error) {
  console.error(error);
});
# Ruby SDK: https://github.com/sendinblue/APIv3-ruby-library

# 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'
end

api_instance = SibApiV3Sdk::ContactsApi.new

create_contact = SibApiV3Sdk::CreateContact.new # CreateContact | Values to create a contact
create_contact = { 'email' => "john@doe.com" }

begin
  #Create a contact
  result = api_instance.create_contact(create_contact)
  p result
rescue SibApiV3Sdk::ApiError => e
  puts "Exception when calling ContactsApi->create_contact: #{e}"
end
# Python SDK: https://github.com/sendinblue/APIv3-python-library
from __future__ import print_function
import time
import sib_api_v3_sdk
from sib_api_v3_sdk.rest 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= "john@doe.com", 
) # CreateContact | Values to create a contact

try:
    # Create a contact
    api_response = api_instance.create_contact(create_contact)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling ContactsApi->create_contact: %s\n" % e)
// Java SDK: https://github.com/sendinblue/APIv3-java-library
// 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
createContact.email("john@doe.com");

try {
    CreateModel result = apiInstance.createContact(createContact);
    System.out.println(result);
} catch (ApiException e) {
    System.err.println("Exception when calling ContactsApi#createContact");
    e.printStackTrace();
}
We also support Go and C#.

Go to our Go SDK documentation:
https://github.com/sendinblue/APIv3-csharp-library

Go to our C# SDK documentation:
https://github.com/sendinblue/APIv3-csharp-library

Rate limiting

The Sendinblue's API allows a maximum 400 request per minute. Between 400 and 2,000 requests per minute, the requests will be slowed down by a random delay up to 2 seconds. Above 2,000 requests per minutes, they will be discarded.

Pagination

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.

Name
Type
Description

limit

integer

The number of results returned per page. The default and maximum value may vary per API

offset

integer

The 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 "https://api.sendinblue.com/v3/contacts?limit=100&offset=2"
     -H "api-key: xkeysib-xxx"
     -H "content-type: application/json"

Responses

Format

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 sucess 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": "123.65.8.22",
      "domain": "mailing.myshop.dom"
    },
    {
      "id": 5,
      "ip": "123.43.21.3",
      "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 Sendinblue API:

HTTP code
Status
Description

200

OK

The request was successful

201

Created

The object was successfully created

202

Accepted

The request was accepted and will be processed

204

No content

The object was successfully updated or deleted

400

Bad request

Request is invalid. Check the error code in JSON

401

Unauthorized

You did not authenticate. Make sure you passed the header api-key

402

Payment Required

Make sure you're account is activated and that you've sufficient credits

403

Forbidden

You do not have the rights to access the ressource. Make sure the api-key you're using is correct

404

Not Found

Make sure your calling an existing endpoint and that the parameters (object id etc.) in the path are correct

405

Method Not Allowed

The verb you're using is not allowed for this endpoint. Make sure you're using the correct method (GET, POST, PUT, DELETE)

Error codes

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

Code
Explanation

invalid_parameter

The value of the parameter you have provided is not valid. Please check the format and the type

missing_parameter

One of the required parameter is missing to perform the request

out_of_range

The value of the parameter you have provided is not included in the authorized range

unauthorized

You are not authorized to do this call

reseller_permission_denied

You need a reseller plan to perform this API call

document_not_found

The parameter value in brackets {} is not found

method_not_allowed

The 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_credits

You don't have enough credit to perform the request. Example : you are trying to send a campaign but your plan has expired

duplicate_parameter

You have duplicated one of the parameter in the request

duplicate_request

The request rate of the very same request is too high

account_under_validation

Your account is under validation

permission_denied

You don't have the permission to perform this request

Sendinblue IP addresses

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

185.107.232.0/22

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.


How the API works


Learn the key concepts on Sendinblue's API

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.