Getting started overview

Integrating with Brevo's API involves a sequence of steps, from setting up your account to making a successful API call. This guide outlines the process for developers looking to use Brevo for email marketing, transactional emails, or SMS services. The core components of getting started include account creation, API key generation, and sending a test request.

Brevo provides client libraries for multiple programming languages, including Node.js, Python, PHP, Ruby, Java, and Go, to facilitate integration. These libraries abstract the underlying HTTP requests, simplifying interaction with the API. The Brevo API is a RESTful API that accepts JSON payloads and returns JSON responses, typical for modern web services. For more detailed information, consult the Brevo developer documentation.

Here's a quick reference for the initial steps:

Create an account and get keys

Before interacting with the Brevo API, you must create a Brevo account. Brevo offers a free tier that allows sending up to 300 emails per day, which is suitable for initial testing and development. During the signup process, you will be prompted to provide basic information and verify your email address. Once your account is active, you can proceed to generate your API key.

1. Sign Up for a Brevo Account: Navigate to the Brevo website and complete the registration process. This typically involves providing an email address, setting a password, and filling out some basic company or personal details.
2. Verify Your Email: After registration, Brevo will send a verification email to the address you provided. Click the link in this email to activate your account.
3. Access Your Dashboard: Log in to your Brevo account dashboard.
4. Navigate to API Keys: In the dashboard, locate and click on the 'SMTP & API' section. This is usually found in the left-hand navigation menu under 'Senders & IPs' or a similar category.
5. Generate a New API Key: On the 'API Keys' tab, click the 'Generate a new API key' button. You will be prompted to give your key a descriptive name. Choose a name that indicates the key's purpose, such as "Development Environment" or "Transactional Emails API".
6. Copy Your API Key: Once generated, your API key will be displayed. It is crucial to copy this key immediately and store it securely, as it will only be shown once. This key is a sensitive credential that authenticates your application to Brevo's services. Treat it like a password.

Brevo API keys are specific to your account and grant access to its resources. Misuse or exposure of an API key could lead to unauthorized access to your Brevo services. Best practices for API key management include using environment variables for storage instead of hardcoding, and implementing key rotation policies. For general security best practices related to API keys, refer to guides like the Google Cloud API keys documentation.

Your first request

After obtaining your API key, you can make your first request. This example uses the Python client library to send a simple transactional email. If you prefer another language, refer to the Brevo Getting Started documentation for examples in Node.js, PHP, Ruby, Java, or Go.

Prerequisites:

• Python 3 installed.
• Brevo API key.

1. Install the Brevo Python SDK

pip install brevo-api

2. Write the Python code

Create a file named send_email.py and add the following code. Replace YOUR_API_KEY with your actual Brevo API key, and update the sender/recipient email addresses.

import brevo_api
from brevo_api.rest import ApiException
import os

# Configure API key authorization: api-key
configuration = brevo_api.Configuration(host = "https://api.brevo.com/v3")
configuration.api_key['api-key'] = 'YOUR_API_KEY'

# Create an instance of the API class
api_instance = brevo_api.TransactionalEmailsApi(brevo_api.ApiClient(configuration))

# Define the email details
send_smtp_email = brevo_api.SendSmtpEmail(
    sender={"name": "Sender Name", "email": "[email protected]"},
    to=[{"name": "Recipient Name", "email": "[email protected]"}],
    subject="Hello from Brevo!",
    html_content="<html><body>
This is my first transactional email!
</body></html>"
)

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}")

3. Run the script

python send_email.py

If successful, you will see a JSON response in your console containing a messageId. The recipient should receive the email shortly. If an error occurs, the ApiException will print details about the issue.

Common next steps

After successfully sending your first email, you may want to explore more advanced features or integrate Brevo deeper into your application workflow:

• Explore Other Email Features: Beyond basic transactional emails, Brevo supports email marketing campaigns, email templates, and contact list management. Review the Brevo API reference for email to understand all available endpoints.
• Implement Webhooks: Brevo offers webhooks to receive real-time notifications about email events (e.g., delivered, opened, clicked). Setting up webhooks can enhance your application's ability to react to user engagement. Information on configuring webhooks is available in the Brevo webhooks documentation.
• Integrate SMS Marketing: If your use case involves SMS, explore the Brevo SMS API. You can send transactional SMS messages, marketing campaigns, and manage SMS contacts.
• Manage Contacts: Use the API to add, update, and manage your contact lists. This is crucial for segmentation and targeted communication.
• Utilize Marketing Automation: Brevo's marketing automation features can be triggered via API, allowing you to automate workflows based on user actions or data changes in your system.
• Review Daily Limits and Pricing: Understand your account's daily sending limits and consider upgrading your Brevo pricing plan if your needs exceed the free tier.

Troubleshooting the first call

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

• Invalid API Key: Double-check that you have copied the entire API key correctly and that there are no leading or trailing spaces. Ensure you are using a v3 API key, as older versions might behave differently.
• Incorrect Endpoint or Host: Confirm that the API endpoint or host URL in your code matches the official Brevo documentation (e.g., https://api.brevo.com/v3).
• Missing Required Parameters: Review the API reference for the specific endpoint you are calling. Ensure all mandatory parameters (e.g., sender email, recipient email, subject for sending emails) are included in your request payload.
• Sender Verification: For sending emails, ensure that the sender email address ('From' address) has been verified in your Brevo account. Unverified senders will prevent emails from being sent.
• Network Issues: Check your internet connection. If you are behind a firewall or proxy, ensure it allows outbound connections to api.brevo.com.
• Rate Limiting: While unlikely for a first call, be aware that Brevo imposes rate limits. If you're rapidly making multiple calls, you might hit these limits. The API response will typically include headers indicating rate limit status.
• Examine API Response and Error Messages: The API will return an error message and a status code if a request fails. Carefully read these messages, as they often pinpoint the exact problem. For example, a 400 Bad Request usually indicates an issue with your request payload, while a 401 Unauthorized points to an API key problem.
• Consult Brevo Documentation: The Brevo developer documentation contains detailed explanations of error codes and troubleshooting guides for common scenarios.