SMS API

The SMS API allows you to send 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 http://example.com

JP specific optional parameters

The additional parameters below are for JP specific usage and recipients:

Name Description Required Data Type Example
jp_kp K-Premium flag No The string true true
jp_kddi_sender Sender ID for au No Numeric 0312341234

Please refer to our K-Premium Service FAQ for more information on the K-Premium Service.

Note

Notes on the jp_kp parameter:

  • If the jp_kp parameter is set to true, the maximum length for ASCII messages are 140 characters
  • For non-ASCII messages, the maximum length is 70 characters

Note

Notes on the message parameter:

  • The maximum length for ASCII messages are 160 characters (unless you’re using jp_kp)
  • For non-ASCII messages, the maximum length is 70 characters

Note

Notes on the recipient parameter:

  • Xoxzo uses the E.164 number format when specifying phone numbers.
  • E.164 dictates that phone numbers must start with the + prefix and country code then followed directly by the mobile number leaving the local 0 prefix .
  • Example of a valid recipient is: +818011234567 with 81 as the Japan country code and 8011234567 as the mobile number.

Note

Notes on the sender parameter:

  • The sender parameter does not require a + sign prefix.
  • You can also specify alphanumeric sender such as XOXZO1 or XOXZO for the sender. In this case, the maximum length for the sender parameter is 10.
  • If the sender parameter contains only digits, the maximum length is 15.

Warning

The sender is sent as through a best effort method and is not guaranteed to be shown on the recipient’s mobile as it is and maybe replaced with an arbitary sender. This is dependent on the policies of the carriers, intermerdiary networks and governments, and they may not honour your request.

Note

Notes on the message parameter:

  • This is the main message that you’ll be sending to the recipient.
  • All messages must be encoded in UTF-8
  • Messages which only contains ASCII based characters will have a maximum length of 160 characters, while other types of messages will have a maximum length of 70 characters

Note

Notes on the callbackurl parameter:

  • When this optional parameter is provided, XOXZO cloud will call this URL when the carrier network notifies us of the SMS delivery status(DLR).
  • XOXZO cloud call the URL with http POST method. Parameters of the callback is similar to “Check SMS status API”. Please see Check SMS status API.
  • Callback URL must return http status 200. Until then, we will retry up to a maximum of ten times.

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

{
    "status": "DELIVERED",
    "sent_time":"2015-08-27 09:22:32",
    "cost": 10,
    "sender": "<sender>",
    "recipient": "<recipient>",
    "url": "https://api.xoxzo.com/sms/messages/<msgid>/",
    "msgid": "<msgid>"
}

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

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 5000 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.

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