SMS API¶
The SMS API allows you to send/receive SMS to supported carriers via beautiful HTTP endpoints.
Send SMS messages API¶
To send a SMS message, make a POST request to the endpoint:
https://api.xoxzo.com/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
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
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>:
https://api.xoxzo.com/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 is an example request using cURL:
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>",
"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>",
"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",
"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:
https://api.xoxzo.com/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>",
"sent_time": null,
"status": "QUEUED",
"url": "https://api.xoxzo.com/sms/messages/<msgid>"
},
{
"cost": 10,
"msgid": "<msgid>",
"recipient": "<recipient>",
"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>",
"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>",
"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>",
"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>",
"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>",
"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
Receive SMS messages API¶
The receive SMS messages API allows you to subscribe to phone numbers and receive incoming SMS.
Finding a SMS In Number via API¶
This API allows for listing and subscribing to a SMS In Number (SIN).
To list available SINs, make a GET request to:
curl -u <SID>:<AUTH_TOKEN> https://api.xoxzo.com/sms/sins/
The response will be a JSON structure, returned with HTTP 200 OK status code like:
HTTP/1.1 200 OK
Allow: GET, HEAD, OPTIONS
Connection: keep-alive
Content-Type: application/json
[
{
"country_code": "81",
"initial_subscription_cost": 37500.0,
"message_rate": 3,
"monthly_cost": 7500.0,
"sin": "815012345678",
"sin_uid": "JPafr34rafic76tf",
"prefix": "50"
},
{
"country_code": "81",
"initial_subscription_cost": 37500.0,
"message_rate": 3,
"monthly_cost": 7500.0,
"sin": "817012345678",
"sin_uid": "JPascfdrwersdf12",
"prefix": "70"
}
]
Response data¶
Name
Description
country_code
The country code for this SIN
initial_subscription_cost
The initial subscription credit cost of subscribing to this SIN
message_rate
The credit cost per incoming message received to this SIN
monthly_cost
The monthly credit cost of subscribing to this SIN
sin
The E.164 version of the SIN, including country code
sin_uid
A unique identifier for this particular SIN
prefix
The local area prefix for this SIN, without the 0
You can also filter using a country code or a prefix:
curl -u <SID>:<AUTH_TOKEN> https://api.xoxzo.com/sms/sins/?country=JP
Or:
curl -u <SID>:<AUTH_TOKEN> https://api.xoxzo.com/sms/sins/?prefix=817
filtering using country or prefix will only return you the relevant SINs based on your filter.
Subscribing to a SMS In Number via API¶
To subscribe to a SIN, send a POST request like:
curl -u <SID>:<AUTH_TOKEN> -d'sin_uid=<sin_uid>' https://api.xoxzo.com/sms/sins/subscriptions/
where <sin_uid> is the value you got from the previous GET request for the number you want to subscribe to.
The response will return with HTTP 201 OK to indicate that the subscription was succesfull.
Warning
Your credits will be charged immediately for the initial subscription cost if your
POSTrequest succeeds
Define a webhook for the SMS In Number via API¶
Each SMS In Number needs to have a webhook that will receive the data when the incoming message was received:
curl -u <SID>:<AUTH_TOKEN> -d'action_url=<url>' https://api.xoxzo.com/sms/sins/subscriptions/<sin_uid>/
The url specified for action_url will be called via POST method when there is incoming message to your subscribed SMS In Number.
Tip
Try subscribing to a local number and see how it works now! Signing up takes only a few minutes and it’s free
Data that will be sent to webhook¶
Following are data that will be sent to webhook:
Name
Description
sender
The sender of the message
sin
The SIN number that’s receiving the message
message
The payload of the message
received_time
The time when the message is received (in UTC)
The data will be sent in JSON format. webhook must return HTTP Successfull 2xx status. Until then, we will retry up to a maximum of ten times.
Getting the list of subscribed SMS In Numbers via API¶
To get the list of your current subscribed SINs, just make a GET request like:
curl -u <SID>:<AUTH_TOKEN> https://api.xoxzo.com/sms/sins/subscriptions/
Unsubscribing to a SMS In Number via API¶
To unsubscribe:
curl -XDELETE -u <SID>:<AUTH_TOKEN> https://api.xoxzo.com/sms/sins/subscriptions/<sin_uid>/