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 (Synchronous)

ℹ️

Difference between synchronous and asynchronous endpoint versions

There are two endpoints for sending an SMS message to a mobile number:

• Send SMS message to a mobile number
• Send SMS message asynchronously to a mobile number

Both the asynchronous and synchronous API endpoints send messages synchronously, the key difference is how they handle request acceptance. The asynchronous endpoint accepts request faster as compared to the synchronous endpoint.

This request uses the endpoint https://api.brevo.com/v3/transactionalSMS/sms with the POST method. A sample cURL request is:

curl --request POST \
     --url https://api.brevo.com/v3/transactionalSMS/sms \
     --header 'accept: application/json' \
     --header 'api-key: YOUR-API-KEY' \
     --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 params are mentioned below:

📘

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 here:

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

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

Send SMS message asynchronously to a mobile number

ℹ️

Difference between synchronous and asynchronous endpoint versions

There are two endpoints for sending an SMS message to a mobile number:

• Send SMS message to a mobile number
• Send SMS message asynchronously to a mobile number

Both the asynchronous and synchronous API endpoints send messages synchronously, the key difference is how they handle request acceptance. The asynchronous endpoint accepts request faster as compared to the synchronous endpoint.

This endpoint provides better response time than the endpoint Send SMS message to a mobile number. This endpoint uses the endpoint https://api.brevo.com/v3/transactionalSMS/send with the POST method. A sample cURL request is:

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": "marketing",
  "tag": "\"tag1\" OR [\"tag1\", \"tag2\"]",
  "webUrl": "http://requestb.in/100lyyx1",
  "unicodeEnabled": true,
  "organisationPrefix": "MyCompany"
}
'

The params are mentioned below:

The response for a successful 201 request is shown here:

{  
  "messageId": 1511882900100020,  
}

A 400 error code means you sent 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. 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.

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.

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.

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