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.
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();
}
// 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' : "john@doe.com" };
apiInstance.createContact(createContact).then(function(data) {
console.log('API called successfully. Returned data: ' + data);
}, function(error) {
console.error(error);
});
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.
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"
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:
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)
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
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.