Step 2 - Send an SMS

Last update: 7 days ago by Irais Aguirre

With the token obtained in the previous step, make a POST to the messaging endpoint, including the Bearer token in the

Authorization

header.


URL	`https://gateway.broadcastermobile.com/services/messaging`
METHOD	POST
HEADERS	Content-Type: application/json Authorization: Bearer [access_token]

Body

{
    "msisdn": [numeric][required],
    "dial": [string][required],
    "message": [String][required],
    "country": [string][recommended],
    "carrier": [String][optional],
    "mask": [String][optional],
    "dataCoding": [String][optional],
    "dlr": [Boolean][optional],
    "schedule": [String][optional][format: ISO-8601],
    "tag": [String][optional],
    "msgClass": [numeric][optional],
    "optionals": [String][optional]
}

Parameters	Description	Required
msisdn	Destination phone number in international format, without the `+` sign. E.g.: `5215512345678`.	Yes
dial	Shortcode or source number. Digits only. E.g.: `"5217000"`.	Yes
message	Text of the SMS to send.	Yes
country	ISO 3166-1 alpha-2 country code. E.g.: `"MX"`, `"CO"`, `"PE"`. Send it whenever you can: it speeds up carrier resolution and reduces `-40` errors.	Recommended
carrier	Name of the destination carrier. If omitted, the system detects it automatically.	No
mask	Alphanumeric sender mask. Requires the capability to be enabled on your account.	No
dataCoding	Message encoding. Omit this field for automatic Unicode detection.	No
dlr	`true` to request a delivery report. Default: `false`. See Delivery report (DLR).	No
schedule	Scheduled send date/time in ISO 8601 format. Must be a future date.	No
tag	Free-form label to identify the send in your reports.	No
msgClass	Message class. Advanced use case.	No
optionals	JSON as a string for advanced options (DLR type, RCS fallback, etc.).	No

Do not send apiKey in the body. The system ignores it and takes it from the token automatically — you do not need to include it.

Example

{
    "msisdn": 5215512345678,
    "dial": "5217000",
    "message": "Your verification code is: 948271",
    "country": "MX"
}

Successful response

{
    "code": 0,
    "mailingId": 4823910,
    "result": "Applied",
    "scheduledAt": null
}

Field	Type	Description
code	number	`0` = successful. Negative value = error.
mailingId	number	Unique ID of the accepted message. Use it to track the send.
result	string	`"Applied"` when the message was accepted.
scheduledAt	string	Scheduled date (if you used `schedule`). `null` for immediate sends.
message	string	Error description (present when `code` ≠ 0).
hint	string	Additional error detail to help with troubleshooting.

All endpoints return HTTP 200 OK. The actual result of the send is indicated in the body by the code field.

Delivery report (DLR)

If you want to know whether the SMS reached the recipient, enable the delivery report by adding dlr: true and the optionals field with registeredDelivery:

{
    "msisdn": 5215512345678,
    "dial": "5217000",
    "message": "Hi, your order has been shipped",
    "country": "MX",
    "dlr": true,
    "optionals": "{\"registeredDelivery\":1}"
}

DLR rules

If you send
```
dlr: true
```
, the
```
optionals
```
field must include
```
registeredDelivery
```
with a valid value.
If you include
```
registeredDelivery
```
in
```
optionals
```
,
```
dlr
```
must be
```
true
```
.

Valid `registeredDelivery` values

Value	Meaning
1	Notifies only on successful delivery.
5	Notifies on delivery or on failure.
11	Notifies on any status change.

External API — Previous

Step 1 - Get the Token

Error codes