The Brevo Transactional Email API allows developers to send transactional emails such as order confirmations, password resets, and account notifications programmatically. It supports single and batch sending, scheduled deliveries, template-based emails, and attachment handling. The API also provides endpoints for tracking email activity including opens, clicks, bounces, and delivery status through detailed event logs and real-time webhooks.
openapi: 3.1.0
info:
title: Brevo Transactional Email API
description: >-
The Brevo Transactional Email API allows developers to send transactional
emails such as order confirmations, password resets, and account
notifications programmatically. It supports single and batch sending,
scheduled deliveries, template-based emails, and attachment handling. The
API also provides endpoints for tracking email activity including opens,
clicks, bounces, and delivery status through detailed event logs and
real-time webhooks.
version: '3.0'
contact:
name: Brevo Support
url: https://help.brevo.com
termsOfService: https://www.brevo.com/legal/termsofuse/
externalDocs:
description: Brevo Transactional Email Documentation
url: https://developers.brevo.com/docs/send-a-transactional-email
servers:
- url: https://api.brevo.com/v3
description: Brevo Production API Server
tags:
- name: Email Activity
description: >-
Track and retrieve transactional email activity including delivery
status, opens, clicks, and bounces.
- name: Email Templates
description: >-
Create and manage reusable email templates for transactional messaging.
- name: Senders
description: >-
Manage sender identities used for transactional email sending.
- name: Transactional Emails
description: >-
Send and manage transactional emails including order confirmations,
password resets, and account notifications.
security:
- apiKeyAuth: []
paths:
/smtp/email:
post:
operationId: sendTransactionalEmail
summary: Send a transactional email
description: >-
Sends a transactional email to one or more recipients. Supports
personalization with dynamic parameters, template-based content,
attachments, and scheduled delivery. Can also send to multiple
recipients in a single call.
tags:
- Transactional Emails
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SendTransactionalEmail'
responses:
'201':
description: Email sent successfully
content:
application/json:
schema:
$ref: '#/components/schemas/SendEmailResponse'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/smtp/email/batch:
post:
operationId: batchSendTransactionalEmails
summary: Batch send transactional emails
description: >-
Sends multiple transactional emails in a single API call. Each email
in the batch can have different recipients, content, and parameters.
Template placeholders can fetch values from the contact database.
tags:
- Transactional Emails
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
messageVersions:
type: array
description: >-
List of email messages to send in the batch.
items:
$ref: '#/components/schemas/SendTransactionalEmail'
responses:
'201':
description: Batch emails sent successfully
content:
application/json:
schema:
$ref: '#/components/schemas/SendEmailResponse'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/smtp/statistics/events:
get:
operationId: getTransactionalEmailEvents
summary: Get transactional email activity events
description: >-
Retrieves all transactional email activity as unaggregated events.
Returns individual event records for deliveries, opens, clicks,
bounces, spam reports, and other email activity.
tags:
- Email Activity
parameters:
- $ref: '#/components/parameters/limitParam'
- $ref: '#/components/parameters/offsetParam'
- name: startDate
in: query
description: >-
Start date for the event query in YYYY-MM-DD format.
schema:
type: string
format: date
- name: endDate
in: query
description: >-
End date for the event query in YYYY-MM-DD format.
schema:
type: string
format: date
- name: event
in: query
description: >-
Filter by event type such as delivered, opened, clicked,
hardBounce, softBounce, blocked, spam, or unsubscribed.
schema:
type: string
enum:
- sent
- delivered
- opened
- clicked
- hardBounce
- softBounce
- blocked
- spam
- invalid
- deferred
- unsubscribed
- name: email
in: query
description: >-
Filter events by recipient email address.
schema:
type: string
format: email
- name: messageId
in: query
description: >-
Filter events by the unique message identifier.
schema:
type: string
- name: templateId
in: query
description: >-
Filter events by the template ID used for sending.
schema:
type: integer
format: int64
responses:
'200':
description: Transactional email events retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/EmailEventReport'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/smtp/statistics/aggregatedReport:
get:
operationId: getAggregatedEmailReport
summary: Get aggregated transactional email statistics
description: >-
Retrieves aggregated statistics for transactional email activity over
a specified period. Returns totals for requests, delivered, opens,
clicks, bounces, and other metrics.
tags:
- Email Activity
parameters:
- name: startDate
in: query
description: >-
Start date for the report in YYYY-MM-DD format.
schema:
type: string
format: date
- name: endDate
in: query
description: >-
End date for the report in YYYY-MM-DD format.
schema:
type: string
format: date
responses:
'200':
description: Aggregated email statistics retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/AggregatedEmailReport'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/smtp/templates:
get:
operationId: listSmtpTemplates
summary: List email templates
description: >-
Retrieves all transactional email templates created in the account.
Templates can be used to send personalized transactional emails
with consistent formatting.
tags:
- Email Templates
parameters:
- $ref: '#/components/parameters/limitParam'
- $ref: '#/components/parameters/offsetParam'
- name: templateStatus
in: query
description: >-
Filter templates by their active status.
schema:
type: boolean
responses:
'200':
description: Templates retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/TemplateList'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
post:
operationId: createSmtpTemplate
summary: Create an email template
description: >-
Creates a new transactional email template with HTML content,
subject line, and sender information. Templates support dynamic
parameters for personalization.
tags:
- Email Templates
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSmtpTemplate'
responses:
'201':
description: Template created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/CreateTemplateResponse'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/smtp/templates/{templateId}:
get:
operationId: getSmtpTemplate
summary: Get an email template
description: >-
Retrieves the details of a specific transactional email template
by its unique identifier.
tags:
- Email Templates
parameters:
- $ref: '#/components/parameters/templateIdParam'
responses:
'200':
description: Template retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/SmtpTemplate'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Template not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
put:
operationId: updateSmtpTemplate
summary: Update an email template
description: >-
Updates an existing transactional email template with new content,
subject line, or sender information.
tags:
- Email Templates
parameters:
- $ref: '#/components/parameters/templateIdParam'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateSmtpTemplate'
responses:
'204':
description: Template updated successfully
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Template not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
delete:
operationId: deleteSmtpTemplate
summary: Delete an email template
description: >-
Permanently deletes a transactional email template by its unique
identifier.
tags:
- Email Templates
parameters:
- $ref: '#/components/parameters/templateIdParam'
responses:
'204':
description: Template deleted successfully
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Template not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/smtp/email/{messageId}:
get:
operationId: getTransactionalEmailContent
summary: Get the content of a sent transactional email
description: >-
Retrieves the personalized content of a previously sent transactional
email including the rendered HTML body, subject line, and recipient
information.
tags:
- Transactional Emails
parameters:
- name: messageId
in: path
required: true
description: >-
The unique message identifier of the sent transactional email.
schema:
type: string
responses:
'200':
description: Email content retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionalEmailContent'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Email not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/senders:
get:
operationId: getSenders
summary: Get email senders
description: >-
Retrieves the list of all sender identities configured in the
account for use with transactional and marketing emails.
tags:
- Senders
parameters:
- name: ip
in: query
description: >-
Filter senders by dedicated IP address.
schema:
type: string
- name: domain
in: query
description: >-
Filter senders by domain name.
schema:
type: string
responses:
'200':
description: Senders retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/SenderList'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
post:
operationId: createSender
summary: Create a new sender
description: >-
Creates a new sender identity that can be used for sending
transactional and marketing emails. The sender must be verified
before use.
tags:
- Senders
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSender'
responses:
'201':
description: Sender created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSenderResponse'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
components:
securitySchemes:
apiKeyAuth:
type: apiKey
in: header
name: api-key
description: >-
Brevo API key passed in the api-key request header for
authentication.
parameters:
limitParam:
name: limit
in: query
description: >-
Maximum number of results to return per request.
schema:
type: integer
format: int64
default: 50
offsetParam:
name: offset
in: query
description: >-
Number of results to skip for pagination.
schema:
type: integer
format: int64
default: 0
templateIdParam:
name: templateId
in: path
required: true
description: >-
The unique identifier of the email template.
schema:
type: integer
format: int64
schemas:
SendTransactionalEmail:
type: object
required:
- sender
- to
properties:
sender:
type: object
description: >-
The sender identity for the email.
properties:
name:
type: string
description: >-
Display name of the sender.
email:
type: string
format: email
description: >-
Email address of the sender.
to:
type: array
description: >-
List of recipient email addresses and optional names.
items:
type: object
required:
- email
properties:
email:
type: string
format: email
description: >-
Recipient email address.
name:
type: string
description: >-
Recipient display name.
cc:
type: array
description: >-
List of CC recipient email addresses.
items:
type: object
properties:
email:
type: string
format: email
description: >-
CC recipient email address.
name:
type: string
description: >-
CC recipient display name.
bcc:
type: array
description: >-
List of BCC recipient email addresses.
items:
type: object
properties:
email:
type: string
format: email
description: >-
BCC recipient email address.
name:
type: string
description: >-
BCC recipient display name.
subject:
type: string
description: >-
Subject line of the email. Required if not using a template.
htmlContent:
type: string
description: >-
HTML body content of the email. Required if not using a template.
textContent:
type: string
description: >-
Plain text body content of the email as a fallback.
templateId:
type: integer
format: int64
description: >-
ID of the template to use for the email content.
params:
type: object
description: >-
Dynamic parameters for template personalization as key-value pairs.
additionalProperties: true
replyTo:
type: object
description: >-
Reply-to address for the email.
properties:
email:
type: string
format: email
description: >-
Reply-to email address.
name:
type: string
description: >-
Reply-to display name.
attachment:
type: array
description: >-
List of file attachments to include with the email.
items:
type: object
properties:
url:
type: string
format: uri
description: >-
URL of the attachment file to download and include.
content:
type: string
description: >-
Base64 encoded content of the attachment.
name:
type: string
description: >-
Filename of the attachment.
headers:
type: object
description: >-
Custom email headers as key-value pairs.
additionalProperties:
type: string
tags:
type: array
description: >-
Tags to categorize the email for tracking purposes.
items:
type: string
scheduledAt:
type: string
format: date-time
description: >-
UTC date-time to schedule the email for future delivery.
SendEmailResponse:
type: object
properties:
messageId:
type: string
description: >-
Unique identifier assigned to the sent email message.
EmailEventReport:
type: object
properties:
events:
type: array
description: >-
List of transactional email activity events.
items:
type: object
properties:
email:
type: string
format: email
description: >-
Recipient email address associated with the event.
date:
type: string
format: date-time
description: >-
UTC date-time when the event occurred.
messageId:
type: string
description: >-
Unique identifier of the email message.
event:
type: string
description: >-
Type of email event that occurred.
enum:
- sent
- delivered
- opened
- clicked
- hardBounce
- softBounce
- blocked
- spam
- invalid
- deferred
- unsubscribed
reason:
type: string
description: >-
Reason for the event if applicable, such as bounce details.
tag:
type: string
description: >-
Tag assigned to the email for categorization.
subject:
type: string
description: >-
Subject line of the email message.
templateId:
type: integer
format: int64
description: >-
Template ID used for the email if applicable.
AggregatedEmailReport:
type: object
properties:
range:
type: string
description: >-
Date range for the aggregated statistics.
requests:
type: integer
format: int64
description: >-
Total number of email send requests.
delivered:
type: integer
format: int64
description: >-
Total number of successfully delivered emails.
hardBounces:
type: integer
format: int64
description: >-
Total number of hard bounces.
softBounces:
type: integer
format: int64
description: >-
Total number of soft bounces.
clicks:
type: integer
format: int64
description: >-
Total number of link clicks.
uniqueClicks:
type: integer
format: int64
description: >-
Total number of unique link clicks.
opens:
type: integer
format: int64
description: >-
Total number of email opens.
uniqueOpens:
type: integer
format: int64
description: >-
Total number of unique email opens.
spamReports:
type: integer
format: int64
description: >-
Total number of spam reports.
blocked:
type: integer
format: int64
description: >-
Total number of blocked emails.
invalid:
type: integer
format: int64
description: >-
Total number of invalid email addresses.
unsubscribed:
type: integer
format: int64
description: >-
Total number of unsubscribes.
TemplateList:
type: object
properties:
count:
type: integer
format: int64
description: >-
Total number of templates available.
templates:
type: array
description: >-
List of email template summaries.
items:
$ref: '#/components/schemas/SmtpTemplate'
SmtpTemplate:
type: object
properties:
id:
type: integer
format: int64
description: >-
Unique identifier of the template.
name:
type: string
description: >-
Name of the template.
subject:
type: string
description: >-
Subject line of the template.
isActive:
type: boolean
description: >-
Whether the template is currently active.
htmlContent:
type: string
description: >-
HTML content of the template body.
sender:
type: object
description: >-
Default sender identity for the template.
properties:
name:
type: string
description: >-
Sender display name.
email:
type: string
format: email
description: >-
Sender email address.
replyTo:
type: string
format: email
description: >-
Default reply-to email address for the template.
createdAt:
type: string
format: date-time
description: >-
UTC date-time when the template was created.
modifiedAt:
type: string
format: date-time
description: >-
UTC date-time when the template was last modified.
CreateSmtpTemplate:
type: object
required:
- templateName
- sender
properties:
templateName:
type: string
description: >-
Name for the new template.
subject:
type: string
description: >-
Default subject line for the template.
htmlContent:
type: string
description: >-
HTML content for the template body.
sender:
type: object
description: >-
Default sender identity for the template.
required:
- email
properties:
name:
type: string
description: >-
Sender display name.
email:
type: string
format: email
description: >-
Sender email address.
replyTo:
type: string
format: email
description: >-
Default reply-to email address.
isActive:
type: boolean
description: >-
Whether to activate the template immediately.
UpdateSmtpTemplate:
type: object
properties:
templateName:
type: string
description: >-
Updated name for the template.
subject:
type: string
description: >-
Updated subject line for the template.
htmlContent:
type: string
description: >-
Updated HTML content for the template body.
sender:
type: object
description: >-
Updated sender identity for the template.
properties:
name:
type: string
description: >-
Sender display name.
email:
type: string
format: email
description: >-
Sender email address.
replyTo:
type: string
format: email
description: >-
Updated reply-to email address.
isActive:
type: boolean
description: >-
Whether the template should be active.
CreateTemplateResponse:
type: object
properties:
id:
type: integer
format: int64
description: >-
Unique identifier of the newly created template.
TransactionalEmailContent:
type: object
properties:
email:
type: string
format: email
description: >-
Recipient email address.
subject:
type: string
description: >-
Rendered subject line of the sent email.
body:
type: string
description: >-
Rendered HTML body of the sent email.
date:
type: string
format: date-time
description: >-
UTC date-time when the email was sent.
messageId:
type: string
description: >-
Unique message identifier.
SenderList:
type: object
properties:
senders:
type: array
description: >-
List of configured sender identities.
items:
type: object
properties:
id:
type: integer
format: int64
description: >-
Unique identifier of the sender.
name:
type: string
description: >-
Display name of the sender.
email:
type: string
format: email
description: >-
Email address of the sender.
active:
type: boolean
description: >-
Whether the sender is verified and active.
CreateSender:
type: object
required:
- name
- email
properties:
name:
type: string
description: >-
Display name for the new sender.
email:
type: string
format: email
description: >-
Email address for the new sender.
CreateSenderResponse:
type: object
properties:
id:
type: integer
format: int64
description: >-
Unique identifier of the newly created sender.
ErrorResponse:
type: object
properties:
code:
type: string
description: >-
Error code identifying the type of error.
message:
type: string
description: >-
Human-readable description of the error.