SMS | Send a transactional message

Transactional SMS provides solution for non-promotional emails using the recipients contact number instead of email address. It is used to send notifications and confirmations like making an online order.

Requirements

Get your API key from your settings (SMTP & API).

If you are new to the API, read more about how the api works.

Send SMS message to a mobile number

This request uses the endpoint ttps://api.brevo.com/v3/transactionalSMS/sms with the POST method. You can send a request with the cURL request below.

curl --request POST \
     --url https://api.brevo.com/v3/transactionalSMS/sms \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "type": "transactional",
  "unicodeEnabled": true,
  "sender": "piyush",
  "recipient": "912240002499",
  "content": "sms content",
  "tag": "t1",
  "webUrl": "www.test.com",
  "organisationPrefix": "TestCompany"
}

The body params for sending and SMS message are mentioned below.

Attribute name	Datatype	Description	Value
sender	String	Name of the sender. The number of characters is limited to 11 for alphanumeric characters and 15 for numeric characters	MyShop
recipient	String	Mobile number to send SMS with the country code	33689965433
content	String	Content of the message. If more than 160 characters long, will be sent as multiple text messages	Enter this code:CCJJG8 to validate your account
type	String	Type of the SMS. Marketing SMS messages are those sent typically with marketing content. Transactional SMS messages are sent to individuals and are triggered in response to some action, such as a sign-up, purchase, etc.	Choice of Transactional and Marketing
tag	String	Tag of the message	accountValidation
webUrl	Url	Webhook to call for each event triggered by the message (delivered etc.)	`http://requestb.in/173lyyx1`
unicodeEnabled	Boolean	Format of the message. It indicates whether the content should be treated as unicode or not.	Boolean true or false
organisationPrefix	String	A recognizable prefix will ensure your audience knows who you are. Recommended by U.S. carriers. This will be added as your Brand Name before the message content. Prefer verifying maximum length of 160 characters including this prefix in message content to avoid multiple sending of same sms.	Brand name like My Company

📘
Additional info for type and content params
type param: To ensure the [STOP CODE] is correctly substituted, you must specify the type as “marketing” when using the transactional SMS API endpoint. If your SMS content includes [STOP CODE], select the type as “marketing.”
content param when type is marketing: On some routes, the short code will automatically replace the alphanumeric SenderID if you do not add an opt-out [STOP CODE].

The response for a successful 201 request is shown below

{
  "reference": "ab1cde2fgh3i4jklmno",
  "messageId": 1511882900176220,
  "smsCount": 2,
  "usedCredits": 0.7,
  "remainingCredits": 82.85
}

If a 402 response code occurrs that means you dont have enough credits in your account to send an SMS.

Get your SMS activity aggregated over a period of time

This request uses the endpoint https://api.brevo.com/v3/transactionalSMS/statistics/aggregatedReport with the GET method. You can send a request with the cURL request below.

curl --request GET \
     --url 'https://api.brevo.com/v3/transactionalSMS/statistics/aggregatedReport?startDate=&endDate=&days=23&tag=' \
     --header 'accept: application/json' \
     --header 'api-key: '

There are some query params which are mentioned below.

Attribute	Datatype	Description	Value
startDate	String	Mandatory if endDate is used. Starting date (YYYY-MM-DD) of the report	2024-01-25
endDate	String	Mandatory if startDate is used. Ending date (YYYY-MM-DD) of the report	2024-02-25
days	int64	Number of days in the past including today (positive integer). Not compatible with startDate and endDate	10
tag	String	Filter on a tag	tagged

After a successful request, the SMS activity response is shown below.

{
  "range": "2015-05-22|2017-11-29",
  "requests": 54,
  "delivered": 16,
  "hardBounces": 5,
  "softBounces": 26,
  "blocked": 4,
  "unsubscribed": 10,
  "replied": 8,
  "accepted": 6,
  "rejected": 14
}

Get your SMS activity aggregated per day

This request uses the endpoint https://api.brevo.com/v3/transactionalSMS/statistics/reports with the GET method. You can send a request with the cURL request below.

curl --request GET \
     --url 'https://api.brevo.com/v3/transactionalSMS/statistics/reports?sort=desc' \
     --header 'accept: application/json'

You can also add more query params above in the --url header, the params are mentioned below in a table.

Attribute	Datatype	Description	Value
startDate	String	Mandatory if endDate is used. Starting date (YYYY-MM-DD) of the report	2024-01-25
endDate	String	Mandatory if startDate is used. Ending date (YYYY-MM-DD) of the report	2024-02-25
days	int64	Number of days in the past including today (positive integer). Not compatible with startDate and endDate	10
tag	String	Filter on a tag	tagged
sort	String	Sort the results in the ascending/descending order of record creation. Default order is descending if sort is not passed	desc

After a successful request, the response looks something like below.

{
  "reports": [
    {
      "date": "2017-04-30",
      "requests": 10756,
      "delivered": 10103,
      "hardBounces": 21,
      "softBounces": 137,
      "blocked": 1026,
      "unsubscribed": 720,
      "replied": 5091,
      "accepted": 2318,
      "rejected": 0,
      "skipped": 0
    },
    {
      "date": "2017-05-01",
      "requests": 18812,
      "delivered": 17499,
      "hardBounces": 34,
      "softBounces": 254,
      "blocked": 1514,
      "unsubscribed": 1090,
      "replied": 10089,
      "accepted": 4393,
      "rejected": 0,
      "skipped": 0
    },
    {
      "date": "2017-05-02",
      "requests": 14321,
      "delivered": 13427,
      "hardBounces": 16,
      "softBounces": 176,
      "blocked": 1646,
      "unsubscribed": 1170,
      "replied": 11563,
      "accepted": 4689,
      "rejected": 0,
      "skipped": 1
    }
  ]
}

Get all your SMS activity (unaggregated events)

This request uses the endpoint https://api.brevo.com/v3/transactionalSMS/statistics/events with the GET method. You can send a request with the cURL request below.

curl --request GET \
     --url 'https://api.brevo.com/v3/transactionalSMS/statistics/events?limit=50&offset=0&sort=desc' \
     --header 'accept: application/json'

The query params for this endpoint are mentioned below.

Attribute	Datatype	Description	Value
startDate	String	Mandatory if endDate is used. Starting date (YYYY-MM-DD) of the report	2024-01-25
endDate	String	Mandatory if startDate is used. Ending date (YYYY-MM-DD) of the report	2024-02-25
days	int64	Number of days in the past including today (positive integer). Not compatible with startDate and endDate	10
tag	String	Filter on a tag	tagged
sort	String	Sort the results in the ascending/descending order of record creation. Default order is descending if sort is not passed	desc
limit	int64	Number of documents per page	50
offset	String	Index of the first document of the page	2
phoneNumber	String	Filter the report for a specific phone number	tag1
event	String	Filter the report for specific events	Includes events like bounces, delivered, accepted etc.

After a successful request, the response looks something like below.

{
  "events": [
    {
      "phoneNumber": "00911059469013",
      "date": "2015-05-20T12:30:00Z",
      "messageId": "1473139351170140",
      "event": "sent",
      "reason": "Recipient is currently unreachable",
      "tag": "cabWaiting"
    },
    {
      "phoneNumber": "00911059469013",
      "date": "2015-05-20T16:30:00Z",
      "messageId": "1473139351170140",
      "event": "delivered",
      "reason": "Recipient is currently unreachable",
      "tag": "cabRequest"
    }
  ]
}

Requirements

Send SMS message to a mobile number

📘Additional info for type and content params

Get your SMS activity aggregated over a period of time

Get your SMS activity aggregated per day

Get all your SMS activity (unaggregated events)

📘
Additional info for `type` and `content` params