Messaging API

Send transactional SMS

View as Markdown

Transactional SMS is a solution for non-promotional SMS using the recipient’s phone number instead of an email address. Use it to send notifications and confirmations, such as for online orders.

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

STOP code and message type

If your SMS content includes a stop/opt-out code, the message is automatically switched to marketing type — you don’t need to (and shouldn’t) set type: "marketing" yourself to handle this. To send as transactional, simply don’t include a stop code in the content.

This endpoint is https://api.brevo.com/v3/transactionalSMS/send with the POST method. You can send either a content string directly, or a templateId with params to fill in a saved template — one of the two is required. A sample cURL request using content:

curl --request POST \
     --url https://api.brevo.com/v3/transactionalSMS/send \
     --header 'accept: application/json' \
     --header 'api-key: YOUR-API-KEY' \
     --header 'content-type: application/json' \
     --data '
{
  "sender": "MyShop",
  "recipient": "33680065433",
  "content": "Enter this code:CAAA08 to validate your account",
  "type": "transactional",
  "tag": "accountValidation",
  "webUrl": "https://webhook.site/100lyyx1",
  "unicodeEnabled": true,
  "organisationPrefix": "MyCompany"
}
'

The params are listed below:

Attribute nameDatatypeDescriptionValue
senderStringName of the sender. The number of characters is limited to 11 for alphanumeric characters and 15 for numeric charactersMyShop
recipientStringMobile number to send SMS with the country code33680005003
contentStringContent of the message. Required if templateId is not passed, ignored if templateId is passed. If more than 160 characters long, will be sent as multiple text messagesEnter this code:CCJJG8 to validate your account
templateIdintegerTemplate ID to send SMS with the template. Overrides content when provided. Required if content is not passed.123
paramsobjectAttributes to fill in the template’s placeholder variables. Only applicable when templateId is used.{"FNAME": "Joe", "LNAME": "Doe"}
typeStringType of the SMS: transactional (default) or marketing. Transactional SMS messages are triggered in response to an action such as a sign-up or purchase. A stop code in the content automatically switches the message to marketing, regardless of what you pass here.Choice of transactional and marketing
tagString or array of stringsTag(s) of the message. Either a single string or an array of up to 10 strings.accountValidation
webUrlUrlWebhook to call for each event triggered by the message (delivered etc.)https://webhook.site/173lyyx1
unicodeEnabledBooleanFormat of the message. It indicates whether the content should be treated as unicode or not.Boolean true or false
organisationPrefixStringA 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

A successful 201 response:

{
  "messageId": 1511882900100020
}

A 400 error code indicates a bad request.

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. Sample cURL request:

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

Query params:

AttributeDatatypeDescriptionValue
startDateStringMandatory if endDate is used. Starting date (YYYY-MM-DD) of the report2024-01-25
endDateStringMandatory if startDate is used. Ending date (YYYY-MM-DD) of the report2024-02-25
daysint64Number of days in the past including today (positive integer). Not compatible with startDate and endDate10
tagStringFilter on a tagtagged

A successful response:

{
  "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. Sample cURL request:

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

Add more query params to the --url value. The params are listed below.

AttributeDatatypeDescriptionValue
startDateStringMandatory if endDate is used. Starting date (YYYY-MM-DD) of the report2024-01-25
endDateStringMandatory if startDate is used. Ending date (YYYY-MM-DD) of the report2024-02-25
daysint64Number of days in the past including today (positive integer). Not compatible with startDate and endDate10
tagStringFilter on a tagtagged
sortStringSort the results in the ascending/descending order of record creation. Default order is descending if sort is not passeddesc

A successful response:

{
  "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. Sample cURL request:

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 listed below.

AttributeDatatypeDescriptionValue
startDateStringMandatory if endDate is used. Starting date (YYYY-MM-DD) of the report2024-01-25
endDateStringMandatory if startDate is used. Ending date (YYYY-MM-DD) of the report2024-02-25
daysint64Number of days in the past including today (positive integer). Not compatible with startDate and endDate10
tagsStringFilter for specific tags, passed as a serialized urlencoded arraytagged
sortStringSort the results in the ascending/descending order of record creation. Default order is descending if sort is not passeddesc
limitint64Number of documents per page50
offsetintegerIndex of the first document of the page2
phoneNumberStringFilter the report for a specific phone number33680005003
eventStringFilter the report for specific eventsIncludes events like bounces, delivered, accepted etc.

A successful response:

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