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 with custom variables.

Before you start

Retrieve your credentials

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

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

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 body types per request.

Request

HTML Body

Text Body

Template

1 curl --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 }'

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. Embed variables in HTML content, plain text, or templates.

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

Dynamic variables (tracking number, delivery date)
Contact attributes (name, address)

Dynamic variables embedded in the request

Pass dynamic variables directly in your API request using the params object 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

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 body types per request.

Request

HTML Body

Text Body

1 curl --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 }'

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.

Open template creation

Open the template creation page in your Brevo dashboard.

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”.

Import template

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

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

Save and activate

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

Get template ID

Return to the templates page and note the template ID (the number after ”#” in the template name). You 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.

Create attribute

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

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

Create webhook

Go to the transactional webhooks page and:

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

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

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"]
>   }'

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.

1	curl --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	}'

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	}