Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Transactional Emails API
version: 1.0.0
servers:
- url: https://api.brevo.com/v3
description: https://api.brevo.com/v3
tags:
- name: transactionalEmails
paths:
/smtp/email:
post:
operationId: sendTransacEmail
summary: Send a transactional email
description: Send a transactional email to one or more recipients, either using inline HTML content or a pre-built template via `templateId`. You can schedule emails for future delivery using `scheduledAt` (UTC, up to 5-minute delay), send multiple personalized versions with `messageVersions` (max 2000 total recipients, 99 per version), and attach files via URL or base64-encoded content. A `sender` and `subject` are required when no `templateId` is provided; when a `templateId` is used, the template''s sender and subject are applied unless overridden.
tags:
- transactionalEmails
parameters:
- name: api-key
in: header
description: The API key should be passed in the request headers as `api-key` for authentication.
required: true
schema:
type: string
responses:
'201':
description: Transactional email sent successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Transactional_emails_sendTransacEmail_Response_201'
'400':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/SendTransacEmailRequestBadRequestError'
requestBody:
description: Request body parameters for sending a transactional email
content:
application/json:
schema:
type: object
properties:
attachment:
type: array
items:
$ref: '#/components/schemas/SmtpEmailPostRequestBodyContentApplicationJsonSchemaAttachmentItems'
description: 'Array of attachment objects. Each attachment must include either an absolute URL (no local file paths) or base64-encoded content, along with the attachment filename. The `name` field is required when `content` is provided. Supported file extensions: xlsx, xls, ods, docx, docm, doc, csv, pdf, txt, gif, jpg, jpeg, png, tif, tiff, rtf, bmp, cgm, css, shtml, html, htm, zip, xml, ppt, pptx, tar, ez, ics, mobi, msg, pub, eps, odt, mp3, m4a, m4v, wma, ogg, flac, wav, aif, aifc, aiff, mp4, mov, avi, mkv, mpeg, mpg, wmv, pkpass, xlsm. When `templateId` is specified: if the template uses the New Template Language format, both `url` and `content` attachment types are supported; if the template uses the Old Template Language format, the `attachment` parameter is ignored.
'
batchId:
type: string
description: UUIDv4 identifier for the scheduled batch of transactional emails. If omitted, a valid UUIDv4 batch identifier is automatically generated.
bcc:
type: array
items:
$ref: '#/components/schemas/SmtpEmailPostRequestBodyContentApplicationJsonSchemaBccItems'
description: 'Array of BCC recipient objects. Each object contains an email address and an optional name.
'
cc:
type: array
items:
$ref: '#/components/schemas/SmtpEmailPostRequestBodyContentApplicationJsonSchemaCcItems'
description: 'Array of CC recipient objects. Each object contains an email address and an optional name.
'
headers:
type: object
additionalProperties:
description: Any type
description: 'Custom email headers (non-standard headers) to include in the email. The `sender.ip` header can be set to specify the IP address used for sending transactional emails (dedicated IP users only). Header names must use Title-Case-Format (words separated by hyphens with the first letter of each word capitalized). Headers not in this format are automatically converted. Standard email headers are not supported. Example: `{"sender.ip":"1.2.3.4", "X-Mailin-custom":"some_custom_value", "Idempotency-Key":"abc-123"}`
'
htmlContent:
type: string
description: 'HTML body content of the email. Required when `templateId` is not provided. Ignored when `templateId` is provided.
'
messageVersions:
type: array
items:
$ref: '#/components/schemas/SmtpEmailPostRequestBodyContentApplicationJsonSchemaMessageVersionsItems'
description: 'Array of message version objects for sending customized email variants. The `templateId` can be customized per version only if a global `templateId` is provided. The `htmlContent` and `textContent` can be customized per version only if at least one of these is present in the global parameters. Global parameters such as `to` (required), `bcc`, `cc`, `replyTo`, and `subject` can be customized per version. Maximum total recipients per API request is 2000. Maximum recipients per message version is 99. Individual `params` objects must not exceed 100 KB. Cumulative `params` across all versions must not exceed 1000 KB. See https://developers.brevo.com/docs/batch-send-transactional-emails for detailed usage instructions.
'
params:
type: object
additionalProperties:
description: Any type
description: 'Key-value pairs for template variable substitution. Only applicable when the template uses the New Template Language format.
'
replyTo:
$ref: '#/components/schemas/SmtpEmailPostRequestBodyContentApplicationJsonSchemaReplyTo'
description: 'Reply-to email address (required) and optional display name. Recipients will use this address when replying to the email.
'
scheduledAt:
type: string
format: date-time
description: 'UTC date-time when the email should be sent (format: YYYY-MM-DDTHH:mm:ss.SSSZ). Include timezone information in the date-time value. Scheduled emails may be delayed by up to 5 minutes.'
sender:
$ref: '#/components/schemas/SmtpEmailPostRequestBodyContentApplicationJsonSchemaSender'
description: 'Sender information. Required when `templateId` is not provided. Specify either an email address (with optional name) or a sender ID. The `name` field is ignored when `id` is provided.
'
subject:
type: string
description: 'Email subject line. Required when `templateId` is not provided.
'
tags:
type: array
items:
type: string
description: Array of tags for categorizing and filtering emails
templateId:
type: integer
format: int64
description: Template identifier
textContent:
type: string
description: 'Plain text body content of the email. Ignored when `templateId` is provided.
'
to:
type: array
items:
$ref: '#/components/schemas/SmtpEmailPostRequestBodyContentApplicationJsonSchemaToItems'
description: 'Array of recipient objects. Each object contains an email address and an optional display name. Required when `messageVersions` is not provided. Ignored when `messageVersions` is provided. Example: `[{"name":"Jimmy", "email":"jimmy@example.com"}, {"name":"Joe", "email":"joe@example.com"}]`
'
/smtp/emails:
get:
operationId: getTransacEmailsList
summary: Get the list of transactional emails on the basis of allowed filters
description: This endpoint will show the list of emails for past 30 days by default. To retrieve emails before that time, please pass startDate and endDate in query filters.
tags:
- transactionalEmails
parameters:
- name: email
in: query
description: '**Mandatory if templateId and messageId are not passed in query filters.** Email address to which transactional email has been sent.
'
required: false
schema:
type: string
- name: templateId
in: query
description: '**Mandatory if email and messageId are not passed in query filters.** Id of the template that was used to compose transactional email.
'
required: false
schema:
type: integer
format: int64
- name: messageId
in: query
description: '**Mandatory if templateId and email are not passed in query filters.** Message ID of the transactional email sent.
'
required: false
schema:
type: string
- name: startDate
in: query
description: '**Mandatory if endDate is used.** Starting date (YYYY-MM-DD) from which you want to fetch the list. **Maximum time period that can be selected is one month**.
'
required: false
schema:
type: string
- name: endDate
in: query
description: '**Mandatory if startDate is used.** Ending date (YYYY-MM-DD) till which you want to fetch the list. **Maximum time period that can be selected is one month.**
'
required: false
schema:
type: string
- name: sort
in: query
description: Sort the results in the ascending/descending order of record creation. Default order is **descending** if `sort` is not passed
required: false
schema:
$ref: '#/components/schemas/SmtpEmailsGetParametersSort'
default: desc
- name: limit
in: query
description: Number of documents returned per page
required: false
schema:
type: integer
format: int64
default: 500
- name: offset
in: query
description: Index of the first document in the page
required: false
schema:
type: integer
format: int64
default: 0
- name: api-key
in: header
description: The API key should be passed in the request headers as `api-key` for authentication.
required: true
schema:
type: string
responses:
'200':
description: List of transactional emails
content:
application/json:
schema:
$ref: '#/components/schemas/Transactional_emails_getTransacEmailsList_Response_200'
'400':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/GetTransacEmailsListRequestBadRequestError'
/smtp/emails/{uuid}:
get:
operationId: getTransacEmailContent
summary: Get the personalized content of a sent transactional email
description: '<Note title="How to get uuid">You can get the uuid using either of the following methods:
Send a GET request to https://api.brevo.com/v3/smtp/emails and pass the message_id in the url. Use your api-key to authenticate the request and you will get your uuid as a response.
The uuid can also be fetched from the transactional logs page in your Brevo account, from the address URL.</Note>'
tags:
- transactionalEmails
parameters:
- name: uuid
in: path
description: Unique id of the transactional email that has been sent to a particular contact
required: true
schema:
type: string
- name: api-key
in: header
description: The API key should be passed in the request headers as `api-key` for authentication.
required: true
schema:
type: string
responses:
'200':
description: Transactional email content
content:
application/json:
schema:
$ref: '#/components/schemas/Transactional_emails_getTransacEmailContent_Response_200'
'400':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/GetTransacEmailContentRequestBadRequestError'
'404':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/GetTransacEmailContentRequestNotFoundError'
/smtp/email/{identifier}:
delete:
operationId: deleteScheduledEmailById
summary: Delete scheduled emails by batchId or messageId
description: Delete scheduled batch of emails by batchId or single scheduled email by messageId
tags:
- transactionalEmails
parameters:
- name: identifier
in: path
description: The `batchId` of scheduled emails batch (must be a valid UUIDv4) or the `messageId` of scheduled email (enclosed in angle brackets with @ sign, e.g. `<...@domain>`).
required: true
schema:
type: string
- name: api-key
in: header
description: The API key should be passed in the request headers as `api-key` for authentication.
required: true
schema:
type: string
responses:
'204':
description: Scheduled email(s) deleted
content:
application/json:
schema:
type: object
properties: {}
'400':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteScheduledEmailByIdRequestBadRequestError'
'404':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteScheduledEmailByIdRequestNotFoundError'
/smtp/emailStatus/{identifier}:
get:
operationId: getScheduledEmailById
summary: Fetch scheduled emails by batchId or messageId
description: Fetch scheduled batch of emails by batchId or single scheduled email by messageId (Can retrieve data upto 30 days old)
tags:
- transactionalEmails
parameters:
- name: identifier
in: path
description: The `batchId` of scheduled emails batch (must be a valid UUIDv4) or the `messageId` of scheduled email (enclosed in angle brackets with @ sign, e.g. `<...@domain>`). When using `messageId`, the `limit`, `offset`, `sort`, and `status` query parameters are ignored.
required: true
schema:
type: string
- name: startDate
in: query
description: Mandatory if `endDate` is used. Starting date (YYYY-MM-DD) from which you want to fetch the list. Cannot be more than 30 days older than the current date.
required: false
schema:
type: string
format: date
- name: endDate
in: query
description: Mandatory if `startDate` is used. Ending date (YYYY-MM-DD) till which you want to fetch the list. Maximum time period that can be selected is one month.
required: false
schema:
type: string
format: date
- name: sort
in: query
description: Sort the results in the ascending/descending order of record creation. Default order is **descending** if `sort` is not passed. Not valid when identifier is `messageId`.
required: false
schema:
$ref: '#/components/schemas/SmtpEmailStatusIdentifierGetParametersSort'
default: desc
- name: status
in: query
description: Filter the records by `status` of the scheduled email batch or message. Not valid when identifier is `messageId`.
required: false
schema:
$ref: '#/components/schemas/SmtpEmailStatusIdentifierGetParametersStatus'
- name: limit
in: query
description: Number of documents returned per page. Not valid when identifier is `messageId`.
required: false
schema:
type: integer
format: int64
default: 100
- name: offset
in: query
description: Index of the first document on the page. Not valid when identifier is `messageId`.
required: false
schema:
type: integer
format: int64
default: 0
- name: api-key
in: header
description: The API key should be passed in the request headers as `api-key` for authentication.
required: true
schema:
type: string
responses:
'200':
description: Scheduled email batches
content:
application/json:
schema:
$ref: '#/components/schemas/Transactional_emails_getScheduledEmailById_Response_200'
'400':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/GetScheduledEmailByIdRequestBadRequestError'
'404':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/GetScheduledEmailByIdRequestNotFoundError'
/smtp/deleteHardbounces:
post:
operationId: deleteHardbounces
summary: Delete hardbounces
description: Delete hardbounces. To use carefully (e.g. in case of temporary ISP failures)
tags:
- transactionalEmails
parameters:
- name: api-key
in: header
description: The API key should be passed in the request headers as `api-key` for authentication.
required: true
schema:
type: string
responses:
'200':
description: No matching hardbounces found for the given filters. The request was processed successfully but no records were deleted.
content:
application/json:
schema:
$ref: '#/components/schemas/Transactional_emails_deleteHardbounces_Response_200'
'400':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteHardbouncesRequestBadRequestError'
requestBody:
description: values to delete hardbounces
content:
application/json:
schema:
type: object
properties:
contactEmail:
type: string
format: email
description: Target a specific email address
endDate:
type: string
description: Ending date (YYYY-MM-DD) of the time period for deletion. The hardbounces until this date will be deleted. Must be greater than or equal to the startDate
startDate:
type: string
description: Starting date (YYYY-MM-DD) of the time period for deletion. The hardbounces occurred after this date will be deleted. Must be less than or equal to the endDate
/smtp/statistics/reports:
get:
operationId: getSmtpReport
summary: Get your transactional email activity aggregated per day
description: This endpoint will show the aggregated stats per day for the past 10 days by default if `startDate` and `endDate` OR `days` is not passed. The date range can not exceed 30 days.
tags:
- transactionalEmails
parameters:
- name: limit
in: query
description: Number of documents returned per page
required: false
schema:
type: integer
format: int64
default: 10
- name: offset
in: query
description: Index of the first document on the page
required: false
schema:
type: integer
format: int64
default: 0
- name: startDate
in: query
description: '**Mandatory if endDate is used.** Starting date of the report (YYYY-MM-DD)
'
required: false
schema:
type: string
- name: endDate
in: query
description: '**Mandatory if startDate is used.** Ending date of the report (YYYY-MM-DD)
'
required: false
schema:
type: string
- name: days
in: query
description: 'Number of days in the past including today (positive integer, maximum 30). _Not compatible with ''startDate'' and ''endDate''_
'
required: false
schema:
type: integer
format: int64
- name: tag
in: query
description: Tag of the emails
required: false
schema:
type: string
- name: sort
in: query
description: Sort the results in the ascending/descending order of record creation. Default order is **descending** if `sort` is not passed
required: false
schema:
$ref: '#/components/schemas/SmtpStatisticsReportsGetParametersSort'
default: desc
- name: api-key
in: header
description: The API key should be passed in the request headers as `api-key` for authentication.
required: true
schema:
type: string
responses:
'200':
description: Aggregated report informations
content:
application/json:
schema:
$ref: '#/components/schemas/Transactional_emails_getSmtpReport_Response_200'
'400':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/GetSmtpReportRequestBadRequestError'
/smtp/statistics/events:
get:
operationId: getEmailEventReport
summary: Get all your transactional email activity (unaggregated events)
description: This endpoint will show the aggregated stats for past 30 days by default if `startDate` and `endDate` OR `days` is not passed. The date range can not exceed 90 days
tags:
- transactionalEmails
parameters:
- name: limit
in: query
description: Number limitation for the result returned
required: false
schema:
type: integer
format: int64
default: 2500
- name: offset
in: query
description: Beginning point in the list to retrieve from.
required: false
schema:
type: integer
format: int64
default: 0
- name: startDate
in: query
description: '**Mandatory if endDate is used.** Starting date of the report (YYYY-MM-DD). Must be lower than equal to endDate
'
required: false
schema:
type: string
- name: endDate
in: query
description: '**Mandatory if startDate is used.** Ending date of the report (YYYY-MM-DD). Must be greater than equal to startDate
'
required: false
schema:
type: string
- name: days
in: query
description: 'Number of days in the past including today (positive integer, maximum 90). _Not compatible with ''startDate'' and ''endDate''_. Defaults to 30 if neither dates nor days are provided.
'
required: false
schema:
type: integer
format: int64
- name: email
in: query
description: Filter the report for a specific email addresses
required: false
schema:
type: string
format: email
- name: event
in: query
description: Filter the report for a specific event type
required: false
schema:
$ref: '#/components/schemas/SmtpStatisticsEventsGetParametersEvent'
- name: tags
in: query
description: Filter the report for tags (serialized and urlencoded array)
required: false
schema:
type: string
- name: messageId
in: query
description: Filter on a specific message id
required: false
schema:
type: string
- name: templateId
in: query
description: Filter on a specific template id
required: false
schema:
type: integer
format: int64
- name: sort
in: query
description: Sort the results in the ascending/descending order of record creation. Default order is **descending** if `sort` is not passed
required: false
schema:
$ref: '#/components/schemas/SmtpStatisticsEventsGetParametersSort'
default: desc
- name: api-key
in: header
description: The API key should be passed in the request headers as `api-key` for authentication.
required: true
schema:
type: string
responses:
'200':
description: Email events report informations
content:
application/json:
schema:
$ref: '#/components/schemas/Transactional_emails_getEmailEventReport_Response_200'
'400':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/GetEmailEventReportRequestBadRequestError'
/smtp/statistics/aggregatedReport:
get:
operationId: getAggregatedSmtpReport
summary: Get your transactional email activity aggregated over a period of time
description: This endpoint will show the aggregated stats for past 90 days by default if `startDate` and `endDate` OR `days` is not passed. The date range can not exceed 90 days
tags:
- transactionalEmails
parameters:
- name: startDate
in: query
description: '**Mandatory if endDate is used.** Starting date of the report (YYYY-MM-DD). Must be lower than equal to endDate
'
required: false
schema:
type: string
- name: endDate
in: query
description: '**Mandatory if startDate is used.** Ending date of the report (YYYY-MM-DD). Must be greater than equal to startDate
'
required: false
schema:
type: string
- name: days
in: query
description: 'Number of days in the past including today (positive integer, maximum 90). _Not compatible with ''startDate'' and ''endDate''_. Defaults to 90 if neither dates nor days are provided.
'
required: false
schema:
type: integer
format: int64
- name: tag
in: query
description: Tag of the emails
required: false
schema:
type: string
- name: api-key
in: header
description: The API key should be passed in the request headers as `api-key` for authentication.
required: true
schema:
type: string
responses:
'200':
description: Aggregated report informations
content:
application/json:
schema:
$ref: '#/components/schemas/Transactional_emails_getAggregatedSmtpReport_Response_200'
'400':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/GetAggregatedSmtpReportRequestBadRequestError'
/smtp/log/{identifier}:
delete:
operationId: deleteAnSmtpTransactionalLog
summary: Delete an SMTP transactional log
description: Delete SMTP transactional log entries identified by a message ID (enclosed in angle brackets with an @ sign) or a valid email address. Optionally narrow the deletion to a specific date range using `from_date` and `to_date` query parameters (YYYY-MM-DD format). The operation also removes any associated stored email preview content.
tags:
- transactionalEmails
parameters:
- name: identifier
in: path
description: MessageId or email address of the transactional log(s) to delete. Must be a valid message ID (enclosed in angle brackets with @ sign) or a valid email address.
required: true
schema:
type: string
- name: from_date
in: query
description: Starting date (YYYY-MM-DD) to narrow down logs for deletion
required: false
schema:
type: string
- name: to_date
in: query
description: Ending date (YYYY-MM-DD) to narrow down logs for deletion
required: false
schema:
type: string
- name: api-key
in: header
description: The API key should be passed in the request headers as `api-key` for authentication.
required: true
schema:
type: string
responses:
'204':
description: Transactional Logs deleted
content:
application/json:
schema:
type: object
properties: {}
'400':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteAnSmtpTransactionalLogRequestBadRequestError'
'404':
description: Message ID not found
content:
application/json:
schema:
$ref: '#/components/schemas/errorModel'
/smtp/templates:
get:
operationId: getSmtpTemplates
summary: Get the list of email templates
description: Retrieve a paginated list of all transactional email templates (including automation templates) with their details such as name, subject, sender, status, HTML content, and timestamps. Results default to 50 per page (max 1000) and are sorted in descending creation order unless overridden. You can filter by active/inactive status using `templateStatus` and by editor type using `editorType` (currently only `richTextEditor` is supported).
tags:
- transactionalEmails
parameters:
- name: templateStatus
in: query
description: Filter on the status of the template. Active = true, inactive = false
required: false
schema:
type: boolean
- name: limit
in: query
description: Number of documents returned per page
required: false
schema:
type: integer
format: int64
default: 50
- name: offset
in: query
description: Index of the first document in the page
required: false
schema:
type: integer
format: int64
default: 0
- name: sort
in: query
description: Sort the results in the ascending/descending order of record creation. Default order is **descending** if `sort` is not passed
required: false
schema:
$ref: '#/components/schemas/SmtpTemplatesGetParametersSort'
default: desc
- name: editorType
in: query
description: Filter on the editor type used to create the template. Currently only `richTextEditor` is supported as a filter value.
required: false
schema:
$ref: '#/components/schemas/SmtpTemplatesGetParametersEditorType'
- name: api-key
in: header
description: The API key should be passed in the request headers as `api-key` for authentication.
required: true
schema:
type: string
responses:
'200':
description: transactional email templates informations
content:
application/json:
schema:
$ref: '#/components/schemas/Transactional_emails_getSmtpTemplates_Response_200'
'400':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/GetSmtpTemplatesRequestBadRequestError'
post:
operationId: createSmtpTempla
# --- truncated at 32 KB (129 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/brevo/refs/heads/main/openapi/brevo-transactionalemails-api-openapi.yml