❗️

API v2 Deprecation Notice

On June 25th 2020 Sendinblue's API v2 started its official deprecation process. The sunset of the platform will be carried out through the current year and will be completely removed by *December 2022

Why do I have to migrate?

We have taken the API v2 and re engineered it to have a wider, simpler and more performant way to integrate Sendinblue's popular features. When upgrading to v3 you can immediately benefit from:

• A more responsive and faster API.
• Improved reference and examples for all the endpoints —Interact with your Sendinblue data straight from the API Reference site.
• Advanced API responses compliant with the OpenAPI Standard.
• A longer list of API calls which allows you to do more actions over your data.
  
  

How do I migrate?

Get a new API v3 key

As part of the improved API v3 functionality we have also done upgrades on security and authentication. You will need to swap your old v2 key to a new v3 key in order to interact with the newest version. This is easily accessible through the SMTP & API configuration page in your Sendinblue account.

What's changing between v2 and v3?

Request and Response schema

Just as in the previous version we keep using the JSON open standard for all response messages. The response attributes have been reduced. You will only get an object when the call has been successfully executed. In case of error code and message will be present.

Headers

• accept: application/json
• api-key: xkeysib-<your_v3_key>
• content-type: application/json

URL change

https://api.sendinblue.com/v3/{resource}

https://api.sendinblue.com/v2.0/{resource}

Success response

{
    "ips": [
       {
      		"id": 3,
      		"ip": "123.65.8.22",
      		"domain": "mailing.myshop.dom"
       }]
}

{
    "code" : "success",
    "message" : "It worked",
    "ips": [
       {
      		"id": 3,
      		"ip": "123.65.8.22",
      		"domain": "mailing.myshop.dom"
    		}]
}

Error response

{
	"code": "invalid_parameter",
	"message": "Key not found in database"
}

{
    "code" : "failure",
    "message" : "Key Not Found In Database",
    "ips":[]
}

Sending transactional emails

Sending transactional emails is one of the most relevant actions done by the API. Following is an example on how to migrate the endpoint.

Please note the following naming changes in the request parameters:

• from in v2 has changed to sender in v3.
• html in v2 has changed to htmlContent in v3.
• text in v2 has changed to textContent in v3.

Request payload

{
  "sender": {
    "name": "John Doe",
    "email": "[email protected]"
  },
  "to": [
    {
      "email": "[email protected]",
      "name": "Bob Jensen"
    }
  ],
  "cc": [
    {    
      "email": "[email protected]",
      "name": "Marie"
    }
  ],
  "replyTo": {
    "email": "[email protected]",
    "name": "Reply-to"
  },
  "htmlContent": "This is the <h1>HTML</h1>",
  "subject": "This is the subject line"
}

{
	"to":{
			"[email protected]":"to whom!"
	},
	"from":[
			"[email protected]",
			"from email!"
	],
	"subject":"This is the subject line",
	"html":"This is the <h1>HTML</h1>",
	"attachment":[
			"https://domain.com/path-to-file/filename1.pdf",
			"https://domain.com/path-to-file/filename2.jpg"
	]
}

Custom headers
In v3 the custom email headers have changed as follows.

• They are passed as part of the request body.
• X-Mailing-Tag is now a separate array named tags.

{
  "headers": {
    "X-Mailin-custom": "Any custom data",
    "sender.ip": "1.2.3.4"
  },
  "tags": [
    {
      "Accounting",
      "May invoices"
    }
  ] 
}

Additional functionality has been added to transactional emails — Benefit from sending templates with customisable attributes in the new advanced templating language. Check out this extended guide on how to use the new endpoint features.

API Clients

All repositories and package managers for API v2 Clients have been archived since May 2020. This means that the libraries will no longer be maintained or extended in the future. You can instead make use of their upgraded versions which encapsulate all the extended functionalities API v3 now offers. We have also included TypeScript as part of our Library line-up.

• C#
• Go
• Java
• Node JS
• PHP
• Python
• Ruby
• TypeScript node