Messaging API

Send a transactional email

Send transactional emails with static or dynamic content using the Messaging API

Transactional emails are automated, non-promotional messages triggered by user actions such as account creation, order confirmations, and password resets.

If you’re new to the API, see the Quickstart guide before sending your first email.

Static content

Send a basic message with a static body or predefined template.

Dynamic content

Send a message enriched with contact attributes or custom variables.

Before you start

1

Retrieve your credentials

Get your API key or configure OAuth 2.0. See the Authentication guide for details.

2

Register an email sender

Configure your sending domain and sender before sending emails. See how to set up your senders for instructions.

Set up a sender

Send a message with static content

Send a simple email with static HTML or text content. Use this for straightforward transactional messages without dynamic variables or advanced template logic.

Example attributes:

Subject line
subject
stringRequired

Hello from Brevo!

Sender details
sender
objectRequired

{ "name" : "Alex from Brevo", "email" : "hello@brevo.com"}

Recipient details
to
object []Required

[{ "name" : "John Doe", "email" : "johndoe@example.com"}]

Message body
htmlContent
string

“<html><head></head><body><p>Hello,</p>this is my first transactional email sent from Brevo.</p></body></html>”

textContent
string

Hello, this is my first transactional email sent from Brevo.

templateId
string

345

Use one of the following message body types:

  • htmlContent: HTML content that defines the message structure and styling
  • textContent: Plain text content for simple messages like password resets or order confirmations
  • templateId: Reference a template created in the Brevo Drag & Drop editor by passing its template ID
    You can only pick one of the three different body types on each request.

Request

1curl --request POST \
2--url https://api.brevo.com/v3/smtp/email \
3--header 'accept: application/json' \
4--header 'api-key:YOUR_API_KEY' \
5--header 'content-type: application/json' \
6--data '{  
7"sender":{  
8"name":"Alex from Brevo",
9"email":"hello@brevo.com"
10},
11"to":[  
12{  
13  "email":"johndoe@example.com",
14  "name":"John Doe"
15}
16],
17"subject":"Hello from Brevo!",
18"htmlContent":"<html><head></head><body><p>Hello,</p>This is my first transactional email sent from Brevo.</p></body></html>"
19}'
POST
https://api.brevo.com/v3/smtp/email
Body

Response

The response includes a messageId that you can use to track deliverability events for this message.

Response
1{
2  "messageId": "<201798300811.5787683@relay.domain.com>"
3}

Send a message with dynamic content

Dynamic content lets you personalize message bodies with attributes that vary per request. You can embed variables in HTML content, plain text, or as templates.

This guide demonstrates dynamic content using an order confirmation email that includes:

Dynamic variables embedded in the request

Pass dynamic variables directly in your API request using the object params to personalize the message body. Variables are included in the request payload alongside the email content.

Example attributes:

Subject line
subject
stringRequired

Hello from Brevo!

Sender details
sender
objectRequired

{ "name" : "Alex from Brevo", "email" : "hello@brevo.com"}

Recipient details
to
object []Required

[{ "name" : "John Doe", "email" : "johndoe@example.com"}]

Dynamic variables
params
object

{ "trackingCode": "JD01460000300002350000", "estimatedArrival" : "Tomorrow" }

Message body
htmlContent
string

<html><head></head><body>Your delivery is expected {{params.estimatedArrival}}.Your tracking code: {{params.trackingCode}}</p></body></html>

textContent
string

Your delivery is expected {{params.estimatedArrival}}.Your tracking code: {{params.trackingCode}}

Use one of the following message body types:

  • htmlContent: HTML content that defines the message structure and styling
  • textContent: Plain text content for simple messages like password resets or order confirmations
You can only pick one of the two different body types on each request.

Request

1curl --request POST \
2--url https://api.brevo.com/v3/smtp/email \
3--header 'accept: application/json' \
4--header 'api-key:YOUR_API_KEY' \
5--header 'content-type: application/json' \
6--data '{  
7"sender":{  
8"name":"Alex from Brevo",
9"email":"hello@brevo.com"
10},
11"to":[  
12{  
13  "email":"johndoe@example.com",
14  "name":"John Doe"
15}
16],
17"subject":"Hello from Brevo!",
18"params": {
19    "trackingCode": "JD01460000300002350000",
20    "estimatedArrival" : "Tomorrow"
21 },
22"htmlContent":"<html><head></head><body>Your delivery is expected {{params.estimatedArrival}}.Your tracking code: {{params.trackingCode}}</p></body></html>"
23}'
POST
https://api.brevo.com/v3/smtp/email
Body

Response

The response includes a messageId that you can use to track deliverability events for this message.

Response
1{
2  "messageId": "<201798300811.5787683@relay.domain.com>"
3}

Create a template with dynamic content

Create the email template in the Brevo dashboard.

1

Open template creation

Open the template creation page in your Brevo dashboard.

2

Configure settings

Set up your template:

  • Template Name: “Order confirmation”
  • Subject Line: “Your new order has been received”
  • From Email: Select an existing sender
  • From Name: Enter your company name

Click “Next Step”.

3

Import template

In the Design tab, select “Import a template” and paste this URL:

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

4

Save and activate

Click “Import”, then “Save & Quit”. On the next page, click “Save and Activate”.

5

Get template ID

Return to the templates page and note the template ID (the number after ”#” in the template name). You’ll need this for API requests.

You can also create templates via the API using the Create an SMTP template endpoint. You can pass HTML content as a string (htmlContent) or via a URL (htmlUrl).

Add a delivery address attribute

Contacts include EMAIL, FIRSTNAME, LASTNAME, and SMS by default. Add a DELIVERYADDRESS attribute for use in the template.

1

Create attribute

Go to Contact > Settings > Contact Attributes & CRM and add a field named DELIVERYADDRESS.

2

Add test contact

Go to your contacts page and create a contact with:

  • FIRSTNAME: John
  • LASTNAME: Doe
  • EMAIL: Your email address
  • DELIVERYADDRESS: 75014 Paris, France
  • Contact list: Select any list

Click “Save and Close”.

Manage contacts via the API using Create contact attribute and Create a contact. For importing contacts, see synchronize contact lists.

Send the transactional email

Use the Send a transactional email endpoint.

Required parameters

  • sender: Sender email and name (must be registered and verified)
    • name overrides your default sender name
  • to: Recipient email and name
    • Email must be a Brevo contact assigned to a contact list
    • Contact must have FIRSTNAME, LASTNAME, EMAIL, and DELIVERYADDRESS attributes
    • name appears in email headers only
  • templateId: Template ID from the templates page or the list templates endpoint
  • params: Transactional parameters, e.g., {"ORDER": 12345, "DATE": "12/06/2019"}

Test in API reference

Test the endpoint in the API Reference. Click “Try it” and enter your API key.

The API reference interface doesn’t support rich JSON body parameters like params. Use the code examples below for full functionality.

The API reference makes real API calls. Check your rate limits and credits before testing.

Code examples

$curl --request POST \
>  --url https://api.brevo.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"
>   }
>}'

Include these headers in each request:

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

Check your inbox for the email.

Track email events with webhooks

Set up webhooks to track email status. Available events:

Sent, Delivered, Opened, Clicked, Soft Bounce, Hard Bounce, Invalid Email, Deferred, Complaint, Unsubscribed, Blocked, Error

1

Create webhook

Go to the transactional webhooks page and:

  • Enter your server URL to receive webhook events
  • Select events to track

transactional webhooks page

Manage webhooks via the API using Create a webhook and Update a webhook.

2

Send test email with tags

After selecting the delivered event (or any other event), send a test email. Brevo POSTs event data to your URL when the event occurs.

Add tags to identify events in your system:

$curl --request POST \
>  --url https://api.brevo.com/v3/smtp/email \
>  --header 'accept: application/json' \
>  --header 'api-key: xkeysib-xxxxxxxxxxx' \
>  --header 'content-type: application/json' \
>  --data '{
>  "sender":{"email":"sender@example.com"},
>  "to":[{"email":"recipient@example.com"}],
>  "replyTo":{"email":"sender@example.com"},
>  "textContent":"This is a transactional email",
>  "subject":"Subject Line",
>  "tags":["myFirstTransactional"]
>  }'
3

Review webhook payload

When your email is delivered, Brevo POSTs this payload to your webhook URL:

1{
2  "event": "delivered",
3  "email": "example@example.com",
4  "id": 26224,
5  "date": "YYYY-MM-DD HH:mm:ss",
6  "ts": 1598634509,
7  "message-id": "<xxxxxxxxxxxx.xxxxxxxxx@domain.com>",
8  "ts_event": 1598034509,
9  "subject": "Subject Line",
10  "tag": "[\"transactionalTag\"]",
11  "sending_ip": "185.41.28.109",
12  "ts_epoch": 1598634509223,
13  "tags": [
14    "myFirstTransactional"
15  ]
16}

The payload structure is consistent for all events of the same type.

See all event payload structures in the webhook responses documentation.