Getting started overview

Integrating with Sendinblue (now Brevo) involves a sequence of steps designed to get developers sending emails or managing contacts programmatically. The API supports various functionalities, including transactional emails, marketing campaigns, SMS messaging, and contact management. This guide focuses on the initial setup: account creation, API key generation, and executing a basic API call to send a transactional email.

Sendinblue provides official SDKs for several programming languages, including Node.js, Python, PHP, Ruby, Java, and Go, which simplify interaction with the RESTful API. For this guide, we will demonstrate examples using both Python and Node.js, common choices for web and application development. The platform also offers a sandbox environment for testing API integrations without affecting live data or sending actual emails to recipients.

A quick reference for the getting started process:

Step What to Do Where
1. Sign Up Create a new Sendinblue account. Sendinblue Pricing page
2. Get API Key Generate a v3 API key from your account dashboard. Sendinblue dashboard > SMTP & API
3. Install SDK Install the appropriate SDK for your chosen language. PackageManager (npm, pip, etc.)
4. Configure Client Initialize the API client with your API key. Your application code
5. Send First Request Execute a basic API call, e.g., send a transactional email. Your application code
6. Monitor Status Check the API response and Sendinblue logs. Sendinblue dashboard > Transactional logs

Create an account and get keys

To begin, you need a Sendinblue account. You can create a free account which allows sending up to 300 emails per day indefinitely, making it suitable for initial development and testing. Navigate to the Sendinblue pricing page and choose the "Free" plan to sign up. The sign-up process requires basic contact information and email verification.

Once your account is active, log in to your Sendinblue dashboard. The API keys are managed under the SMTP & API section:

  1. From the dashboard, click on your account name in the top right corner.
  2. Select "SMTP & API" from the dropdown menu.
  3. Navigate to the "API Keys" tab.
  4. Click the "Generate a new API key" button.
  5. Provide a descriptive name for your API key (e.g., "Development Integration" or "My First API Key").
  6. Copy the generated API key immediately. Sendinblue does not display the full key again for security reasons. Treat your API key as sensitive credentials, similar to a password. Do not hardcode it directly into public repositories or client-side code. Best practices include using environment variables or a secure configuration management system to store and access your API keys, as recommended for managing AWS access keys securely.

Sendinblue API keys are used for authentication with all API v3 endpoints. Each key typically has full access to your account's API features. If granular permissions are required for specific applications, you might consider creating dedicated sub-accounts or using distinct API keys for different environments (development, staging, production) to limit potential impact in case of a compromise.

Your first request

After obtaining your API key, the next step is to make an initial API call. We will demonstrate sending a simple transactional email using both Python and Node.js SDKs. This involves installing the relevant SDK, configuring it with your API key, and then calling the sendTransacEmail method.

Python Example

First, install the Sendinblue Python SDK:

pip install sib-api-v3-sdk

Next, create a Python script (e.g., send_email.py) and add the following code. Replace YOUR_API_KEY, SENDER_EMAIL, SENDER_NAME, RECIPIENT_EMAIL, and RECIPIENT_NAME with your actual details.

import sib_api_v3_sdk
from sib_api_v3_sdk.rest import ApiException
import os

# Configuration
configuration = sib_api_v3_sdk.Configuration()
configuration.api_key['api-key'] = os.environ.get('SENDINBLUE_API_KEY', 'YOUR_API_KEY')

# Create a Sendinblue API instance
api_instance = sib_api_v3_sdk.TransactionalEmailsApi(sib_api_v3_sdk.ApiClient(configuration))

# Define the email parameters
send_smtp_email = sib_api_v3_sdk.SendSmtpEmail(
    to=[{"email": "RECIPIENT_EMAIL", "name": "RECIPIENT_NAME"}],
    bcc=None,
    cc=None,
    reply_to=None,
    headers={"Some-Custom-Header": "Unique-ID-1234"},
    subject="Hello from Sendinblue API!",
    html_content="<html><body><h1>This is a test email.</h1><p>Sent via the Sendinblue Python SDK.</p></body></html>",
    sender={"email": "SENDER_EMAIL", "name": "SENDER_NAME"},
    tags=["getting_started"]
)

try:
    # Send the email
    api_response = api_instance.send_transac_email(send_smtp_email)
    print(api_response)
except ApiException as e:
    print(f"Exception when calling SMTPApi->send_transac_email: {e}")

Before running, ensure SENDER_EMAIL is a verified sender in your Sendinblue account to avoid delivery issues. You can verify senders under "Senders & IPs" in your Sendinblue dashboard. Execute the script:

python send_email.py

Node.js Example

First, install the Sendinblue Node.js SDK:

npm install sib-api-v3-sdk

Next, create a JavaScript file (e.g., sendEmail.js) and add the following code. Replace placeholders as in the Python example.

const SibApiV3Sdk = require('sib-api-v3-sdk');
const defaultClient = SibApiV3Sdk.ApiClient.instance;
const apiKey = defaultClient.authentications['api-key'];
apiKey.apiKey = process.env.SENDINBLUE_API_KEY || 'YOUR_API_KEY';

const apiInstance = new SibApiV3Sdk.TransactionalEmailsApi();

const sendSmtpEmail = new SibApiV3Sdk.SendSmtpEmail();

sendSmtpEmail.subject = "Hello from Sendinblue API (Node.js)!";
sendSmtpEmail.htmlContent = "<html><body><h1>This is a test email.</h1><p>Sent via the Sendinblue Node.js SDK.</p></body></html>";
sendSmtpEmail.sender = { "email": "SENDER_EMAIL", "name": "SENDER_NAME" };
sendSmtpEmail.to = [{ "email": "RECIPIENT_EMAIL", "name": "RECIPIENT_NAME" }];
sendSmtpEmail.tags = ["getting_started_nodejs"];

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

Execute the script:

node sendEmail.js

Upon successful execution, you should see a response object containing a messageId. This ID can be used to track the status of the sent email in your Sendinblue account's transactional logs. Check your RECIPIENT_EMAIL inbox for the test email. If it's not delivered, check your spam folder or review the transactional logs in the Sendinblue dashboard for delivery status and error messages.

Common next steps

After successfully sending your first email, several common next steps can enhance your integration with Sendinblue:

  • Verify Sender Domain: For improved deliverability and to remove Sendinblue branding from free plan emails, it is recommended to verify your sender domain. This involves adding specific DNS records (TXT records for SPF and DKIM) to your domain registrar. For details on how DNS records work and their importance in email verification, refer to a Cloudflare guide on adding DNS records.
  • Explore Transactional Email Templates: Instead of sending raw HTML content, you can create and manage email templates directly within the Sendinblue dashboard. The API allows you to send templated emails by referencing their ID, which simplifies content management and ensures consistent branding.
  • Contact Management: Integrate with Sendinblue's contact management API to add, update, and retrieve contact information. This is crucial for building and segmenting your audience for marketing campaigns.
  • Webhooks Configuration: Set up webhooks to receive real-time notifications about events such as email delivery status (delivered, opened, clicked, bounced) or new contact subscriptions. Webhooks are essential for building responsive applications that react to user engagement.
  • Marketing Automation: Begin building automated workflows using Sendinblue's marketing automation features. The API can trigger these workflows based on user actions or contact updates, enabling personalized customer journeys.
  • SMS API: If your strategy includes SMS communication, explore the SMS API to send transactional or marketing SMS messages programmatically.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some troubleshooting steps:

  • Check API Key: Double-check that the API key in your code exactly matches the one generated in your Sendinblue dashboard. Ensure there are no leading or trailing spaces. The API key for v3 is a long alphanumeric string.
  • Environment Variables: If using environment variables, verify they are correctly set in your execution environment. For example, in Bash, use echo $SENDINBLUE_API_KEY to confirm the variable's value. Restart your terminal or IDE if you've recently set new variables.
  • Sender Verification: Ensure the SENDER_EMAIL used in your API call is a verified sender in your Sendinblue account. Unverified senders can lead to API errors or emails being blocked.
  • Recipient Email Validity: Confirm that the RECIPIENT_EMAIL is a valid, existing email address. Sending to non-existent addresses can result in bounces.
  • API Response and Error Messages: Carefully review the error message returned by the API. Sendinblue's API provides structured error responses that often indicate the specific problem, such as invalid parameters, authentication failures, or rate limit issues.
  • Sendinblue Logs: Access the "Transactional" logs section in your Sendinblue dashboard. This area provides detailed delivery reports and error messages for each email sent via the API, which can help diagnose issues not immediately apparent from the API response.
  • Rate Limits: Be aware of API rate limits. If you send too many requests in a short period, you might receive a 429 Too Many Requests error. Implement exponential backoff or ensure your application adheres to the documented limits.
  • SDK vs. Raw HTTP: While SDKs abstract much of the HTTP complexity, if issues persist, you can try sending a raw HTTP request using tools like curl to isolate whether the problem is with your SDK integration or the API call itself. Refer to the Sendinblue API reference for specific endpoint details.