Migration Guide for API v2 users

A detailed guide on how to achieve a successful migration and integrate to the API v3 version.

❗️

API v2 Deprecation Notice

On June 25th 2020 Sendinblue's API v2 started its official deprecation process. Its sunset date has been scheduled for June 25th 2021.

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.

.

Where to find Sendinblue API v3 key in your settings.




You can also create a new API v3 key from your API Console. If you need to get the API v3 key directly from your code, we've also created an endpoint in the API v2 which will create and return an API v3 key

curl -H 'api-key:yourApiV2Key' -X POST -d '{"name":"My v3 key name"}' 'https://api.sendinblue.com/v2.0/account/generateapiv3key'

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":[]
}

You can refer to the list of error messages for [API here](https://developers.sendinblue.com/docs/how-it-works#error-codes)

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.

Header v2

Header v3

X-Mailin-custom : "Any custom data"

X-Mailin-custom:"Any custom data"

X-Mailin-IP: 1.2.3.4

sender.ip:1.2.3.4

X-Mailin-Tag: "A custom tag"

tags : [{"A custom tag"}]

{
  "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.

Endpoints

Here you will find a list of all v2 endpoints and their equivalent on API v3.

Updated 9 months ago


What's Next

Endpoint Mapping

Migration Guide for API v2 users


A detailed guide on how to achieve a successful migration and integrate to the API v3 version.

Suggested Edits are limited on API Reference Pages

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