SMS API

The SMS API supports two sending modes: template SMS and freeform SMS. Template SMS is the default for standard accounts, while freeform SMS is available only to approved trusted partners.

Send SMS messages API Template SMS uses approved message templates with validated variables. Freeform SMS allows a fully custom message body, but access is restricted.

Overview

Use template SMS when you want predictable, structured messages such as OTPs, alerts, reminders, and notifications.

Use freeform SMS only when your account has been explicitly enabled for it.

Authentication

All endpoints require authentication using your account credentials.

Example:

curl -u <SID>:<AUTH_TOKEN> https://api.xoxzo.com/sms/templates/

Template management

For template CRUD operations and management, check the following documentation:

Please refer to the SMS Templates API for detailed information on template management.

Template message sending

Send SMS via Template API

To send an SMS using an approved template, make a POST request to the endpoint followed by <template_id>:

https://api.xoxzo.com/sms/templates/<template_id>/messages/

with the following parameters:

Name	Description	Required	Example
sender	Sender ID (alphanumeric max 10 chars; numeric only max 15 chars)	Yes	TestSender
recipient	Recipient phone number in E.164 format	Yes	+81987654321
variables	JSON object mapping each placeholder name to its value	Yes	{“name”: “Alice”}

Note

Only APPROVED templates can be used for sending. Attempting to send with a PENDING template will return an error.

Examples

Below is an example request using cURL:

curl -u <SID>:<AUTH_TOKEN> -X POST \
  https://api.xoxzo.com/sms/templates/<template_id>/messages/ \
  -H "Content-Type: application/json" \
  -d '{
    "sender": "TestSender",
    "recipient": "+81987654321",
    "variables": {
      "name": "Sample_name",
      "salary": "Sample_salary"
    }
  }'

Tip

To use other parameters like link tracking, callback url. Please see the SMS Parameters Table for more details.

The response would be a JSON structure, returned with HTTP 201 CREATED status code:

HTTP/1.1 201 CREATED
Content-Type: application/json

[
    {
        "msgid": "<msgid>"
    }
]

Note

Notes on the variables parameter:

• All variable keys must match the placeholder names defined in the template content exactly.

• Missing or extra keys may result in an error or unresolved placeholders in the sent message.

Check Template Message Status API

All messages sent for a template

To check the status of all SMS messages sent through a specific template, make a GET request to the endpoint:

https://api.xoxzo.com/sms/templates/<template_id>/messages/

Below is an example request using cURL:

curl -u <SID>:<AUTH_TOKEN> \
  https://api.xoxzo.com/sms/templates/<template_id>/messages/

Single message by message ID

To check the status of a specific message sent via a template, make a GET request to the endpoint followed by <msg_id>:

https://api.xoxzo.com/sms/templates/messages/<msg_id>/

Below is an example request using cURL:

curl -u <SID>:<AUTH_TOKEN> \
  https://api.xoxzo.com/sms/templates/messages/<msg_id>/

Tip

Response fields are equivalent to the standard Check SMS status API — including status, cost, msgid, recipient, sender, sent_time, and url. Please see Check SMS status API.

Send Freeform SMS

Freeform SMS is available only to approved partners.

Use this endpoint when you need to send a custom message body without template restrictions.

To send a SMS message, make a POST request to the endpoint:

POST /sms/messages/

with the following parameters:

Name	Description	Required	Data Type	Example
message	Message body	Yes	UTF-8	こんにちは
recipient	Message recipient	Yes	E.164	+8190123456789
sender	Sender ID	Yes	Alphanumeric	Xoxzo1
callbackurl	Callback URL	No	URL	http://example.com
tags	Tags	No	UTF-8	tag1,tag2
track_link	Enable link tracking	No	The string true	true
lt_callbackurl	Link tracking callback URL	No	URL	http://example.com

Please refer to notes and warnings in the previous section Send Templated SMS regarding parameters.

Examples

Below is an example request using cURL:

curl -u <SID>:<AUTH_TOKEN> --data-urlencode 'recipient=<recipient>' --data-urlencode 'sender=<sender>' --data-urlencode 'message=<message>' https://api.xoxzo.com/sms/messages/

The <message> in the above example must be encoded in UTF-8 before sending.

The response would be a JSON structure, returned with HTTP 201 CREATED status code:

HTTP/1.1 201 CREATED
Content-Type: application/json

[
    {
        "msgid": "<msgid>"
    }
]

Response data

Name	Description
msgid	The unique message id for this message

If there’s invalid parameters given, HTTP 400 BAD REQUEST status code will be returned. For example, if the message parameter is missing, the HTTP response should be like this:

HTTP/1.1 400 BAD REQUEST
Content-Type: application/json

{
    "message": [
        "This field is required."
    ]
}

Tip

It’s faster to actually try some test code againts the API to see immediate results. Signing up takes only a few minutes and it’s free

Check SMS status API

To check a message status, make a GET request to the endpoint followed by <msgid>

For Template SMS:

GET /sms/templates/<id>/messages/<msgid>/

For Freeform SMS:

GET /sms/messages/<msgid>/

Every time you send a SMS, you will get a response which contains <msgid>. Use this <msgid> to check SMS status.

Examples

Below are example requests using cURL:

curl -u <SID>:<AUTH_TOKEN> https://api.xoxzo.com/sms/templates/<templateid>/messages/<msgid>/
curl -u <SID>:<AUTH_TOKEN> https://api.xoxzo.com/sms/messages/<msgid>/

The response would be a JSON structure, returned with HTTP 200 OK status code:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "tags": [
        "tag1",
        "tag2"
    ],
    "url": "https://api.xoxzo.com/sms/messages/<msgid>/",
    "recipient": "<recipient>",
    "parts": 1,
    "cost": 10,
    "sent_time": "2019-03-05 00:37:44",
    "sender": "<sender>",
    "msgid": "<msgid>",
    "status": "DELIVERED"
}

Below is a sample of a response for a message that failed to be delivered, returned with a HTTP 200 OK status code:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "FAIL",
    "sent_time": "2015-09-13 12:47:53",
    "cost": 10,
    "msgid": "<msgid>",
    "parts": 1,
    "recipient": "<recipient>",
    "sender": "<sender>",
    "url": "https://api.xoxzo.com/sms/messages/<msgid>/"
}

Response data

Name	Description
status	The status of the sent message
cost	The cost in credits of this message
msgid	The unique message id for this message
recipient	The recipient of this message
sender	The set sender
sent_time	The sent time of the message in UTC
url	The URL of this message status
tags	The tags assigned to this message. If no tags are assigned, empty list [] will be set.

If the track_link is enabled, following information are also included.

Name	Key	Description
link_tracking	accessed	true if the link is accessed already, false if not
	accessed_on	The time when the link was first accessed
	link	The link originally set in the message
	shortlink	The shortened link

example of the response:

{
    "cost": 15.0,
    "link_tracking": {
        "accessed": false,
        "accessed_on": "",
        "link": "http://www.example.com",
        "shortlink": "https://xoz.so/dbNL4"
    },
    "msgid": "oxgyFO6tfwYkHLIMbURrz5smCv9QT423",
    "recipient": "+818012345678",
    "parts": 1,
    "sender": "XOXZO",
    "sent_time": "2020-10-09 02:37:47",
    "status": "DELIVERED",
    "tags": [],
    "url": "https://api.xoxzo.com/sms/messages/oxgyFO6tfwYkHLIMbURrz5smCv9QT423/"
}

Sent Messages List API

You can pull a list of sent messages by making a GET request to the endpoint.

For Template SMS:

GET /sms/templates/<id>/messages/

For Freeform SMS:

GET /sms/messages/

The sent messages results will be sorted based on their newest sent_time. This API is useful for creating logs.

You can also pull sent messages for a specified sent date using sent_date parameter followed by an operator and a date.

Name	Description	Required
sent_date	UTC based date when the message was sent with following format: YYYY-mm-dd. Should be within 90 days from today.	Yes

You can use following operator to get a certain date or a range of sent dates from the sent messages:

Operator	Name
<=	less than equal
<	less than
=	equal
>	greater than
>=	greater than equal

Note

• The maximum amount of sent messages that can be pulled are limited to 30,000 messages.

• Only sent messages within 90 days ago that can be be pulled.

• This API supports only one operator and one specified sent date on each request.

• All dates are based on UTC.

Warning

• This API call is limited to use up to 3 requests/hour.

Examples of response data

The response data returned by the API is equivalent to what you get from the Check SMS status API

Pull all sent messages

Below is an example of request using cURL to pull sent messages:

curl -u <SID>:<AUTH_TOKEN> https://api.xoxzo.com/sms/messages/

The response would be a JSON structure, returned with HTTP 200 OK status code:

HTTP/1.0 200 OK
Content-Type: application/json

[
    {
       "cost": 0,
       "msgid": "<msgid>",
       "recipient": "<recipient>",
       "sender": "<sender>",
       "parts": 1,
       "sent_time": null,
       "status": "QUEUED",
       "url": "https://api.xoxzo.com/sms/messages/<msgid>"
    },
    {
       "cost": 10,
       "msgid": "<msgid>",
       "recipient": "<recipient>",
       "parts": 1,
       "sender": "<sender>",
       "sent_time": "2016-03-04 00:00:00",
       "status": "DELIVERED",
       "url": "https://api.xoxzo.com/sms/messages/<msgid>"
    },
]

Pull sent messages on a specified date

Below is an example of request using cURL to pull sent messages that were sent on 4 March 2016:

curl -u <SID>:<AUTH_TOKEN> https://api.xoxzo.com/sms/messages/?sent_date=2016-03-04

The response would be a JSON structure, returned with HTTP 200 OK status code:

HTTP/1.0 200 OK
Content-Type: application/json

[
    {
       "cost": 10,
       "msgid": "<msgid>",
       "recipient": "<recipient>",
       "parts": 1,
       "sender": "<sender>",
       "sent_time": "2016-03-04 10:15:00",
       "status": "DELIVERED",
       "url": "https://api.xoxzo.com/sms/messages/<msgid>"
    },
    {
       "cost": 10,
       "msgid": "<msgid>",
       "recipient": "<recipient>",
       "parts": 1,
       "sender": "<sender>",
       "sent_time": "2016-03-04 00:00:00",
       "status": "DELIVERED",
       "url": "https://api.xoxzo.com/sms/messages/<msgid>"
    },
]

Below is an example of request using cURL to pull sent messages that were sent before and on 4 March 2016:

curl -u <SID>:<AUTH_TOKEN> https://api.xoxzo.com/sms/messages/?sent_date<=2016-03-04

The response would be a JSON structure, returned with HTTP 200 OK status code:

HTTP/1.0 200 OK
Content-Type: application/json

[
    {
       "cost": 10,
       "msgid": "<msgid>",
       "recipient": "<recipient>",
       "parts": 1,
       "sender": "<sender>",
       "sent_time": "2016-03-04 10:15:00",
       "status": "DELIVERED",
       "url": "https://api.xoxzo.com/sms/messages/<msgid>"
    },
    {
       "cost": 10,
       "msgid": "<msgid>",
       "recipient": "<recipient>",
       "parts": 1,
       "sender": "<sender>",
       "sent_time": "2016-03-04 00:00:00",
       "status": "DELIVERED",
       "url": "https://api.xoxzo.com/sms/messages/<msgid>"
    },
    {
       "cost": 10,
       "msgid": "<msgid>",
       "recipient": "<recipient>",
       "parts": 1,
       "sender": "<sender>",
       "sent_time": "2016-02-15 11:30:47",
       "status": "DELIVERED",
       "url": "https://api.xoxzo.com/sms/messages/<msgid>"
    },
]

No sent messages on a specified date

If there’s no sent messages on specified date, empty list with HTTP 200 OK status code will be returned.

Below is an example of request using cURL to pull sent messages that were sent on 30 January 2016:

curl -u <SID>:<AUTH_TOKEN> https://api.xoxzo.com/sms/messages/?sent_date=2016-01-30

Since there’s no message sent on 30 January 2016, the response would an empty list returned with HTTP 200 OK status code:

HTTP/1.0 200 OK
Content-Type: application/json

[]

Invalid requests example

If the specified date is in invalid format, HTTP 400 BAD REQUEST status code will be returned.

Below is an example of request using cURL to pull sent messages with invalid sent date format:

curl -u <SID>:<AUTH_TOKEN> https://api.xoxzo.com/sms/messages/?sent_date=2016-02-30

Since 30 February 2016 is invalid date, HTTP 400 BAD REQUEST status code will be returned explaining that the sent_date format is invalid:

HTTP/1.0 400 Bad Request
Content-Type: application/json

{
    "sent_date": [
        "Invalid sent_date format"
    ]
}

If the specified date is more than 90 days ago, HTTP 400 BAD REQUEST status code will be returned.

Below is an example of request using cURL to pull sent messages with sent date more than 90 days ago:

curl -u <SID>:<AUTH_TOKEN> https://api.xoxzo.com/sms/messages/?sent_date=2015-02-28

Since 28 February 2015 is more than 90 days ago, HTTP 400 BAD REQUEST status code will be returned asking for a valid sent_date:

HTTP/1.0 400 Bad Request
Content-Type: application/json

{
    "sent_date": [
        "Invalid sent_date"
    ]
}

If the parameter is incorrectly specified, HTTP 400 BAD REQUEST status code will be returned.

Below is an example of request using cURL to pull sent messages with incorrect parameter:

curl -u <SID>:<AUTH_TOKEN> https://api.xoxzo.com/sms/messages/?sent_data=2016-02-28

Since sent_data is not a correct parameter, HTTP 400 BAD REQUEST status code will be returned asking for sent_date parameter:

HTTP/1.0 400 Bad Request
Content-Type: application/json

{
    "sent_date": [
        "This field is required"
    ]
}

Common message statuses

This is a list of statuses that you can find in the status data:

Message status	Description
QUEUED	Message put into queue and will be delivered shortly
DELIVERED	Message successfully delivered
DELIVERING	Sending message in progress
FAIL	Failed to send message

Error responses

The API returns standard HTTP status codes for invalid requests or unauthorized access.

Common errors:

Status code	Meaning
400	Bad request. The request could not be processed.
401	Unauthorized. Authentication failed.
403	Forbidden. The account does not have access to the requested feature.
404	Not found. The requested resource does not exist.
422	Unprocessable entity. Validation failed.

Example validation error:

{
  "variables": {
    "code": [
      "This field is required."
    ]
  }
}