Messaging API v1 Introduction

Table of Contents

Finding your API Key

You must first request access to the API from your Skycore account manager. Once the API is turned on, you can find your API_KEY in the API Settings page under your ‘Account’ dropdown.

Making API requests

GET Request – with URL encoded key/value pairs. The API URL is https://secure.skycore.com/API/wxml/1.3/.

POST Request – with XML data passed inside an ‘xml’ variable.

Note: You must URL Encode the values in the query string of your GET Requests. Failure to do so may result in the API failing to fully interpret your request. For example this query string &data_full_name=John Smith&data_age=35 would need to be encoded &data_full_name=John+Smith&data_age=35 (space replaced with plus sign)

Receiving API callbacks

POST XML – to the Postback URL defined in your Account’s API Settings page. Postback notifications are forwarded to your server individually every second and require an HTTP STATUS 200 response.

We expect your server to accept our postback within 10 seconds by responding with a standard HTTP STATUS 200 header (success). If establishing a connection to your Postback URL takes longer than 10 seconds, the connection will time out and be dropped. If the connection times out or the HTTP code is not 200 we will retry the notification again five minutes later for a maximum of 5 retries per notification.

API Limitations

You may have a throughput limit on your account. If your API requests exceed the throughput on your account then you may have some latency in the delivery of your messages. There may also be limits on the number of API calls allowed per second/minute/day. These limits will be published in your API Settings page.

Authentication

Authenticating your API call can be done in two ways:

apikey – Each API request must contain the accounts APIKEY. Some API requests may also require an MD5 encrypted password.

Authentication Error codes: E100, E101, E102, E103, E104, E105, E106, E107, E108, E109

Error XML Example:

<RESPONSE>
  <STATUS>Failure</STATUS>
  <ERRORCODE>E101</ERRORCODE>
  <ERRORINFO> 'action' required</ERRORINFO>
</RESPONSE>

Special Considerations

Always Use International Number Format: You must use international format when sending SMS or MMS. International format includes both the country code with the phone number. We use the country code to determine the routing of the message. There should be no dialing prefixes (eg 00 or 001) or special characters such as the plus symbol when submitting messages. (e.g. ’642111111′ not ‘+642111111′)

For example the US number (774)-319-9144 in international number format would be 17743199144 because the USA country code is 1.

HTTP API PostBack

Certain messaging, email, and wallet API will generate a PostBack notification. Here you can turn on or off certain PostBacks. If you turn a particular PostBack on, make sure to provide the appropriate PostBack URL for the PostBack and press the ‘Save’ button.

Settings FAQs

How can I get access to the API for my account?

Contact us to activate the API settings on your account.

How does the HTTP API work?

An HTTP request is sent either through a GET request or an XML POST request.

RequestDescription
GETA GET request is in the form of a URL containing an action query string. The request is sent to our servers and our platform responds with a status. The typical structure of the request is$api_url/api?action=$action&api_key=$api_key&data1=$data1&data2=$data2…
XMLUse POST to send an XML to the API url. Our server receives the XML and executes the action encoded. The typical structure of the XML is$action
$api_key
$data1
$data2
API varsDescription
actionThe name of the API. For instance, if you want to send an SMS, you would use the sendSMS API and pass the value ‘sendSMS’ in the ‘action’ field.
api_key The api_key is a unique string of characters that identifies the account using the API. All API requests require the api_key to be passed within the ‘api_key’ field. An API key is generated for each account and can be found in the API settings page.
data Each API generally has optional or mandatory data that can be passed within each request. For instance, if you want to send an SMS, you would need to include the phone number to send the SMS to and thus pass the phone number in the ‘to’ field.

Is HTTPS the only protocol I can use with the API?

No, you may use standard HTTP but we highly recommend that you use HTTPS.

Can I receive API notifications about account activity?

Yes, you can via PostBack notifications. You can receive notifications when someone subscribes or unsubscribes from a campaign. You can also receive notifications upon message receipts or delivery confirmations.

What is SMS/MMS MT DLR?

SMS/MMS MT DLR is for delivery receipts. If you turn these PostBacks on, we will notify you when a message is sent and delivered to an end user.

What are stuck messages?

Stuck MMS messages are messages that the system was unable to process and send. Stuck SMS messages are messages that the system was unable to process the first time and again after the retry period of 5 minutes. Stuck SMS messages may become unstuck during subsequent retries.

Stuck messages indicate there may be some issues such as unreachable gateway server, parse error/sending execution terminated, data missing, or missing/unreachable pass/dynamic image/custom content. The stuck message will be cleared after the queue is cleaned up in 3 days.

Resources

API Error Codes

Postback Notification Codes