Send a transactional email

Learn how to send a transactional email for an existing template and adding dynamic content

Transactional emails are used for all non-promotional emails: send them when a user has created an account, when they have made an order, when request a new password...

Using Sendinblue services, you can create email templates for each scenario.
You may trigger your transactional email - transactional email - An email sent as a result of a contact's request or action (e.g. account creation, purchase confirmations, password resets, notifications, etc.). These are all non-promotional emails and are different from newsletters (or emails targeted to many contacts at once) template to send using one of two methods:

  • Via the SMTP API (v3) using the “send a transactional email” call.
  • Via SMTP relay.
    This method is used by many popular plugins to deliver emails created by the plugin using our SMTP platform.

What you will learn from this tutorial

In this tutorial, you will learn how to:

  • send an order confirmation transactional email

  • use an existing template with dynamic contact attributes (contact name, address) and transactional parameters (order number, expected date of delivery).

:bulb+: If you are not familiar with these terms, read more about email templates here.

This is the email you should get by the end of the tutorial:

Transactional email containing dynamic values for the order number, the client name, address, and the delivery date

Transactional email containing dynamic values for the order number, the client name, address, and the delivery date

Requirements

Get your API key - API key - The unique identifier related to your account that is used to authenticate requests made to SendinBlue API. Get it from your settings (SMTP & API) and pass it to your request header under the key `api-key`. from your settings (SMTP & API).

If you are new to the API, read more about how the api works.
If you cannot get your API key - API key - The unique identifier related to your account that is used to authenticate requests made to SendinBlue API. Get it from your settings (SMTP & API) and pass it to your request header under the key `api-key`. , make sure that your Sendinblue SMTP account is activated.

Create a test template that includes dynamic content

In this tutorial, we'll be sending an order confirmation email to a contact.

To get started quickly, let's create the email template from Sendinblue dashboard.

  1. First, go to the template creation page

    Under Template Name, enter "Order confirmation"
    Under Subject Line, enter "Your new order has been received"
    Pick an existing sender for the From Email
    Enter your company name under From Name
    Click the "Next Step" button when you are done

Transactional email template creation page

Transactional email template creation page

There are several methods to create a template, we'll use the "Import a template" using a template model URL.

Import a template using a shared template URL

Import a template using a shared template URL

Select the "Import a template" tab, and copy and paste the following Shared Template URL:

https://my.sendinblue.com/iNF7GRiE34wzuyVRWobyyLLNbttWwwKn8CQLDhU7kui0HXu4tZG_ZzZ6Ng--

Click "Import" next to the URL. You should be redirected to the following page:

Sendinblue transactional email template editor

Sendinblue transactional email template editor

Template dynamic values

:bulb+: Notice the different placeholders in {{ }} :

  • contact (relative to the contact)

  • params (relative to the transactional email - transactional email - An email sent as a result of a contact's request or action (e.g. account creation, purchase confirmations, password resets, notifications, etc.). These are all non-promotional emails and are different from newsletters (or emails targeted to many contacts at once) ).

We will explain later how to provide them while sending a transactional email with the API. Read more about the difference in this tutorial about email templates.

Click the "Save & Quit" button, then on the new page " Save and Activate"

Finally, save and activate your template

Finally, save and activate your template

Go back to the templates page and save the template id of the one you just created for later.

The id of the template is the number after the "#" after the template name

The id of the template is the number after the "#" after the template name

Template creation using the API

Creating a template using the API is possible, but more limited. Using the Create an smtp template endpoint, you can create a template:

  • by passing the html content as a string (htmlContent)
  • by passing the html content available at a URL (htmlUrl)

Add a contact attribute for the delivery address

By default, a contact comes with the attributes EMAIL, FIRSTNAME, LASTNAME, SMS. Let's add the DELIVERYADDRESS so we can use it fill our template when sending an email.

To go fast, go to the contact attributes page (under Contact > Settings > Contact Attributes & CRM) and add a new field DELIVERYADDRESS.

Edit your contacts "Normal Attributes"

Edit your contacts "Normal Attributes"

Then go to your contact page and add a new contact:

FIRSTNAME: Thomas
LASTNAME: Bianchi
EMAIL: set up your email to receive the test email
DELIVERYADDRESS: 176 Boulevard des fleurs, 75014 Paris, France
Select any contact list - contact list - Contact lists allow you to break up and manage large numbers of contacts more easily. You can import files of up to 250 million entries into your lists and segment your contacts according to your own criteria. Clear and intelligently targeted lists will help optimize deliverability, open rates, and overall campaign performance! you want to import this contact into

Click " Save and Close".

Create a new contact though Sendinblue dashboard

Create a new contact though Sendinblue dashboard

Managing contacts

:bulb+: These features are also available through the API. The endpoints that will help you are Creates contact attribute and Create a contact. You can also follow the tutorial on how to synchronise contact lists to be guided through the steps.

:+1+: That's it! Now let's send our first email!

Send your first transactional email

Let's learn how to use the API. The best way to know what's possible and how to use each endpoint is to go to the API Reference.

Under SMTP > Send a transactional email, you can find the description of the endpoint:

Send transactional email details on Sendinblue API Reference

Send transactional email details on Sendinblue API Reference

We will go over the 6 points outlined in the screenshot above.

1. Endpoint and method

To create send a transactional email - transactional email - An email sent as a result of a contact's request or action (e.g. account creation, purchase confirmations, password resets, notifications, etc.). These are all non-promotional emails and are different from newsletters (or emails targeted to many contacts at once) , you need to call https://api.sendinblue.com/v3/smtp/email using the method POST

Sendinblue API endpoint and method to send a transactional email

Sendinblue API endpoint and method to send a transactional email

2. Body and Path parameters to send in your request

Sendinblue API body parameters to send a transactional email

Sendinblue API body parameters to send a transactional email

There are many available parameters available for this request. These are the ones we'll need:

  • sender: Enter your sender email and name
    :bulb+: the sender email must me a sender registered and verified in Sendinblue
    :bulb+: the sender name parameter here can override the default sender name you have set
  • to: Enter your recipient email and name
    :bulb+: the recipient email should be a contact registered in Sendinblue and assigned to a contact list. That contact should have the attributes FIRSTNAME, LASTNAME, EMAIL, DELIVERYADDRESS defined.
    :bulb+: the recipient name here is the name that will be attached to the email recipient. It will appear in the email headers/metadata and not in the email body.
  • templateId: Enter your template id
    Get the list from the templates page or using the endpoint to get the list of SMTP templates
  • params: the value we will use is {"ORDER": 12345, "DATE": "12/06/2019"}

3. Response that you should expect

If everything goes well, you should get a success response (code 201) with a JSON body giving you the id of the message sent.
ex: {"messageId":"<201906041124.44340027797@smtp-relay.mailin.fr>"}

If the parameters you entered are wrong, you'll get a 400 error along with an error message and error code. Find the list of errors here.

Here, typical errors will be:

  • the sender does not exists
  • an email address is invalid
  • the template does not exists
  • the api-key is missing or wrong
  • the header Content-Type: application/json is missing from your request

Read more about Troubleshooting issues with transactional emails

4. A button to try out the endpoint from the interface

You can try the API using the API reference interface. For that, click the " Try it" button and enter you API key - API key - The unique identifier related to your account that is used to authenticate requests made to SendinBlue API. Get it from your settings (SMTP & API) and pass it to your request header under the key `api-key`. . Fill in the fields you want in the body params form below.

If everything goes well, you should have received an email to the email address you provided in the request.

:bulb+: Notice that the order number and delivery date will be missing from the email received. The reason is that using the API reference interface, you cannot specify rich JSON body parameters like the params to provide DATE and ORDER, so you'll have to use the code snippets and test using cURL or using other integrations. Go to next section for more details.

API Reference limitations and rating

When you try an endpoint, you will make a real call to the API.
Make sure to check rate limits and your credits as the API reference will use them to make the requests (when sending an email or an sms for instance).

Read more about SendinBlue sending email bandwidth and quota

5. Code snippets for you to copy and paste

When you are ready of if you want to make more advanced calls, you can copy the code provided in the right panel section.

Code snippets to send a transactional email using Sendinblue API in several languages

Code snippets to send a transactional email using Sendinblue API in several languages

:bulb+: Notice: The code snippets in the API Reference are only there for you to test your API quickly and in the language that suits you.

:+1+: For your integration, we recommend you use our API clients that will provide you with shortcuts and ease of integration.
Available API clients - API clients - To make coding against APIs easier, SendinBlue provides client libraries that can reduce the amount of code you need to write and make your code more robust. A client library is a set of code that developers can add to their projects. It provides chunks of code that do the basic things an application needs to do in order to interact with the API. and their documentations:

Here are sample codes using the API clients - API clients - To make coding against APIs easier, SendinBlue provides client libraries that can reduce the amount of code you need to write and make your code more robust. A client library is a set of code that developers can add to their projects. It provides chunks of code that do the basic things an application needs to do in order to interact with the API. . Before using then, follow the installation guide from each documentations linked above.

curl --request POST \
  --url https://api.sendinblue.com/v3/smtp/email \
  --header 'accept: application/json' \
  --header 'api-key:YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --data '{  
   "to":[  
      {  
         "email":"testmail@example.com",
         "name":"John Doe"
      }
   ],
   "templateId":8,
   "params":{  
      "name":"John",
      "surname":"Doe"
   },
   "headers":{  
      "X-Mailin-custom":"custom_header_1:custom_value_1|custom_header_2:custom_value_2|custom_header_3:custom_value_3",
      "charset":"iso-8859-1"
   }
}'
curl --request POST \
  --url https://api.sendinblue.com/v3/smtp/email \
  --header 'accept: application/json' \
  --header 'api-key:YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --data '{  
   "sender":{  
      "name":"Sender Alex",
      "email":"senderalex@example.com"
   },
   "to":[  
      {  
         "email":"testmail@example.com",
         "name":"John Doe"
      }
   ],
   "subject":"test mail",
   "htmlContent":"<html><head></head><body><h1>Hello this is a test email from sib</h1></body></html>",
   "headers":{  
      "X-Mailin-custom":"custom_header_1:custom_value_1|custom_header_2:custom_value_2|custom_header_3:custom_value_3",
      "charset":"iso-8859-1"
   }
}'
<?php
require_once(__DIR__ . '/vendor/autoload.php');

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

// Uncomment below line to configure authorization using: partner-key
// $config = SendinBlue\Client\Configuration::getDefaultConfiguration()->setApiKey('partner-key', 'YOUR_API_KEY');

$apiInstance = new SendinBlue\Client\Api\SMTPApi(
    // 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
);
$sendSmtpEmail = new \SendinBlue\Client\Model\SendSmtpEmail(); // \SendinBlue\Client\Model\SendSmtpEmail | Values to send a transactional email
$sendSmtpEmail['to'] = array(array('email'=>'testmail@example.com', 'name'=>'John Doe'));
$sendSmtpEmail['templateId'] = 59;
$sendSmtpEmail['params'] = array('name'=>'John', 'surname'=>'Doe');
$sendSmtpEmail['headers'] = array('X-Mailin-custom'=>'custom_header_1:custom_value_1|custom_header_2:custom_value_2');

try {
    $result = $apiInstance->sendTransacEmail($sendSmtpEmail);
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling SMTPApi->sendTransacEmail: ', $e->getMessage(), PHP_EOL;
}
?>
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';

// Uncomment below two lines to configure authorization using: partner-key
// var partnerKey = defaultClient.authentications['partner-key'];
// partnerKey.apiKey = 'YOUR API KEY';

var apiInstance = new SibApiV3Sdk.SMTPApi();

var sendSmtpEmail = new SibApiV3Sdk.SendSmtpEmail(); // SendSmtpEmail | Values to send a transactional email

sendSmtpEmail = {
	to: [{
		email: 'testmail@example.com',
		name: 'John Doe'
	}],
	templateId: 59,
	params: {
		name: 'John',
		surname: 'Doe'
	},
	headers: {
		'X-Mailin-custom': 'custom_header_1:custom_value_1|custom_header_2:custom_value_2'
	}
};

apiInstance.sendTransacEmail(sendSmtpEmail).then(function(data) {
  console.log('API called successfully. Returned data: ' + data);
}, function(error) {
  console.error(error);
});
# 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'

  # Uncomment below line to configure API key authorization using: partner-key
  # config.api_key['partner-key'] = 'YOUR API KEY'

end

api_instance = SibApiV3Sdk::SMTPApi.new

send_smtp_email = SibApiV3Sdk::SendSmtpEmail.new # SendSmtpEmail | Values to send a transactional email

send_smtp_email = {
  'to'=>[{
    'email'=>'testmail@example.com',
    'name'=>'John Doe'
  }],
  'templateId'=>59,
  'params'=> {
    'name'=>'John',
    'surname'=>'Doe'
  },
  'headers'=> {
    'X-Mailin-custom'=>'custom_header_1:custom_value_1|custom_header_2:custom_value_2'
  }
};

begin
  #Send a transactional email
  result = api_instance.send_transac_email(send_smtp_email)
  p result
rescue SibApiV3Sdk::ApiError => e
  puts "Exception when calling SMTPApi->send_transac_email: #{e}"
end
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'

# Uncomment below lines to configure API key authorization using: partner-key
# configuration = sib_api_v3_sdk.Configuration()
# configuration.api_key['partner-key'] = 'YOUR_API_KEY'

# create an instance of the API class
api_instance = sib_api_v3_sdk.SMTPApi(sib_api_v3_sdk.ApiClient(configuration))
send_smtp_email = sib_api_v3_sdk.SendSmtpEmail(to=[{"email":"testmail@example.com","name":"John Doe"}], template_id=56, params={"name": "John", "surname": "Doe"}, headers={"X-Mailin-custom": "custom_header_1:custom_value_1|custom_header_2:custom_value_2|custom_header_3:custom_value_3", "charset": "iso-8859-1"}) # SendSmtpEmail | Values to send a transactional email

try:
    # Send a transactional email
    api_response = api_instance.send_transac_email(send_smtp_email)
    pprint(api_response)
except ApiException as e:
    print("Exception when calling SMTPApi->send_transac_email: %s\n" % e)
// This example is for Typescript-node

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

var apiInstance = new SibApiV3Sdk.SendSmtpEmail()

// 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 sendSmtpEmail = {
	to: [{
		email: 'testmail@example.com',
		name: 'John Doe'
	}],
	templateId: 59,
	params: {
		name: 'John',
		surname: 'Doe'
	},
	headers: {
		'X-Mailin-custom': 'custom_header_1:custom_value_1|custom_header_2:custom_value_2'
	}
};


apiInstance.sendTransacEmail(sendSmtpEmail).then(function(data) {
  console.log('API called successfully. Returned data: ' + data);
}, function(error) {
  console.error(error);
});

For each request, make sure to include the following headers:

  • api-key: xkeysib-xxxxxxxxxxxxxxxxx
  • content-type: application/json
  • accept: application/json

:+1+: Check your emails! Congratulations, you've just sent your first transactional email using Sendinblue API!


Send a transactional email


Learn how to send a transactional email for an existing template and adding dynamic content

Suggested Edits are limited on API Reference Pages

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