The Brevo Transactional SMS API allows developers to send non-promotional SMS messages such as order confirmations, delivery notifications, and verification codes using recipients' phone numbers. It supports sending individual messages with customizable sender names and provides endpoints for tracking SMS delivery status and activity. The API is designed for time-sensitive notifications that require immediate delivery to mobile devices.
openapi: 3.1.0
info:
title: Brevo Transactional SMS API
description: >-
The Brevo Transactional SMS API allows developers to send non-promotional
SMS messages such as order confirmations, delivery notifications, and
verification codes using recipients' phone numbers. It supports sending
individual messages with customizable sender names and provides endpoints
for tracking SMS delivery status and activity. The API is designed for
time-sensitive notifications that require immediate delivery to mobile
devices.
version: '3.0'
contact:
name: Brevo Support
url: https://help.brevo.com
termsOfService: https://www.brevo.com/legal/termsofuse/
externalDocs:
description: Brevo Transactional SMS Documentation
url: https://developers.brevo.com/docs/transactional-sms-endpoints
servers:
- url: https://api.brevo.com/v3
description: Brevo Production API Server
tags:
- name: SMS Statistics
description: >-
Retrieve delivery reports and activity statistics for transactional
SMS messages.
- name: Transactional SMS
description: >-
Send transactional SMS messages for notifications, verifications,
and alerts.
security:
- apiKeyAuth: []
paths:
/transactionalSMS/sms:
post:
operationId: sendTransactionalSms
summary: Send a transactional SMS
description: >-
Sends a transactional SMS message to a recipient phone number.
Supports customizable sender names and message content. The
message is delivered immediately for time-sensitive notifications.
tags:
- Transactional SMS
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SendTransactionalSms'
responses:
'201':
description: SMS sent successfully
content:
application/json:
schema:
$ref: '#/components/schemas/SendSmsResponse'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/transactionalSMS/statistics/events:
get:
operationId: getSmsEvents
summary: Get transactional SMS activity events
description: >-
Retrieves detailed event-level data for transactional SMS messages
including delivery status, bounces, and recipient interactions.
tags:
- SMS Statistics
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: phoneNumber
in: query
description: >-
Filter events by recipient phone number.
schema:
type: string
- name: event
in: query
description: >-
Filter by event type such as delivered, sent, softBounce,
hardBounce, or unsubscribed.
schema:
type: string
enum:
- sent
- accepted
- delivered
- replied
- softBounce
- hardBounce
- subscribe
- unsubscribe
- skip
- rejected
- name: tags
in: query
description: >-
Filter events by tag assigned to the SMS.
schema:
type: string
responses:
'200':
description: SMS events retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/SmsEventReport'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/transactionalSMS/statistics/reports:
get:
operationId: getSmsReports
summary: Get transactional SMS statistics reports
description: >-
Retrieves detailed delivery reports for transactional SMS messages
over a specified date range. Returns per-day statistics for sent,
delivered, and bounced messages.
tags:
- SMS Statistics
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
- name: days
in: query
description: >-
Number of days for the report, starting from today.
schema:
type: integer
- name: tag
in: query
description: >-
Filter reports by tag.
schema:
type: string
responses:
'200':
description: SMS reports retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/SmsStatisticsReport'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/transactionalSMS/statistics/aggregatedReport:
get:
operationId: getAggregatedSmsReport
summary: Get aggregated transactional SMS statistics
description: >-
Retrieves aggregated statistics for transactional SMS activity
over a specified period. Returns totals for sent, delivered,
and bounced messages.
tags:
- SMS Statistics
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
- name: days
in: query
description: >-
Number of days for the report, starting from today.
schema:
type: integer
- name: tag
in: query
description: >-
Filter by tag.
schema:
type: string
responses:
'200':
description: Aggregated SMS statistics retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/AggregatedSmsReport'
'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
schemas:
SendTransactionalSms:
type: object
required:
- sender
- recipient
- content
properties:
sender:
type: string
description: >-
Name or number displayed as the SMS sender. Must be between
3 and 11 characters for alphanumeric senders.
minLength: 3
maxLength: 11
recipient:
type: string
description: >-
Recipient phone number in international format with country
code prefix.
content:
type: string
description: >-
Text content of the SMS message.
maxLength: 160
type:
type: string
description: >-
Type of SMS message to send.
enum:
- transactional
- marketing
default: transactional
tag:
type: string
description: >-
Tag for categorizing the SMS for reporting purposes.
webUrl:
type: string
format: uri
description: >-
Webhook URL to receive delivery status notifications.
SendSmsResponse:
type: object
properties:
reference:
type: string
description: >-
Unique reference identifier for the sent SMS message.
messageId:
type: integer
format: int64
description: >-
Unique message ID assigned to the SMS.
smsCount:
type: integer
description: >-
Number of SMS segments used to send the message.
usedCredits:
type: number
format: float
description: >-
Number of SMS credits consumed.
remainingCredits:
type: number
format: float
description: >-
Remaining SMS credits in the account.
SmsEventReport:
type: object
properties:
events:
type: array
description: >-
List of transactional SMS activity events.
items:
type: object
properties:
phoneNumber:
type: string
description: >-
Recipient phone number.
date:
type: string
format: date-time
description: >-
UTC date-time when the event occurred.
messageId:
type: string
description: >-
Unique identifier of the SMS message.
event:
type: string
description: >-
Type of SMS event that occurred.
enum:
- sent
- accepted
- delivered
- replied
- softBounce
- hardBounce
- subscribe
- unsubscribe
- skip
- rejected
reason:
type: string
description: >-
Reason for the event if applicable.
tag:
type: string
description: >-
Tag assigned to the SMS.
SmsStatisticsReport:
type: object
properties:
reports:
type: array
description: >-
Daily SMS statistics reports.
items:
type: object
properties:
date:
type: string
format: date
description: >-
Date for the statistics.
requests:
type: integer
format: int64
description: >-
Number of SMS send requests.
delivered:
type: integer
format: int64
description: >-
Number of successfully delivered SMS.
hardBounces:
type: integer
format: int64
description: >-
Number of hard bounces.
softBounces:
type: integer
format: int64
description: >-
Number of soft bounces.
blocked:
type: integer
format: int64
description: >-
Number of blocked SMS.
unsubscribed:
type: integer
format: int64
description: >-
Number of unsubscribes.
AggregatedSmsReport:
type: object
properties:
range:
type: string
description: >-
Date range for the aggregated statistics.
requests:
type: integer
format: int64
description: >-
Total SMS send requests.
delivered:
type: integer
format: int64
description: >-
Total successfully delivered SMS.
hardBounces:
type: integer
format: int64
description: >-
Total hard bounces.
softBounces:
type: integer
format: int64
description: >-
Total soft bounces.
blocked:
type: integer
format: int64
description: >-
Total blocked SMS.
unsubscribed:
type: integer
format: int64
description: >-
Total unsubscribes.
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.