Message Delivery Service API Documentation

This document details how to use the Gigahost Message Delivery Service to deliver Short Messages to cellphones and other capable devices. It also details how to track the sent messages, along with other related operations.

The API uses normal HTTP requests and is highly RESTful. XML is used extensively for responses.

Connecting to the Service

To ensure great reliability and service, this Message Service uses a robust architecture where multiple message delivery gateways can function at the same time. Should one message gateway happen to be out of service, your application can make use of any of the other available gateways to send off messages. For example, at a given moment the following two gateways could be active and functioning:

gw1.tel.gigahost.dk
gw2.tel.gigahost.dk

However, this list might change, and therefore the information about the currently available gateways is stored in DNS as SRV records. To ensure high reliability, your application must first perform a DNS lookup for the SRV records of _sms._tcp.tel.gigahost.dk to find out which gateways can be used. An example of a SRV lookup with the command-line tool dig is shown here:

$ dig _sms._tcp.tel.gigahost.dk srv

[...]

;; ANSWER SECTION:
_sms._tcp.tel.gigahost.dk. 26347 IN	SRV	10 0 443 gw1.tel.gigahost.dk.
_sms._tcp.tel.gigahost.dk. 26347 IN	SRV	10 0 443 gw2.tel.gigahost.dk.
[...]

As is seen in the above example, two gateways were returned in the SRV records. These can be used in any order, but in case one gateway does not respond, your application should proceed to try another. Our code examples show how to do this in various languages.

Once the hostname (such as gw1.tel.gigahost.dk) has been found in the SRV records, an HTTPS request should be made on port 443. In the following, the gw1.tel.gigahost.dk gateway will be used as an example.

Authentication

To authenticate, you need a special API password. If you have a Gigahost.dk user, you can create an API password in the control center. The username for the message gateway is the same as for the Control Center.

You may authenticate with HTTP basic authentication. Since connections always use SSL, it is secure to use HTTP basic authentication.

Getting the Remaining Message Credits

It is only possible to send messages as long as there is an adequate number of messages on the account. Messages can be topped up using the Gigahost Control Center.

A credit inquiry request will return the remaining number of credits. The unit for the credits is the number of messages that can be sent. Note that sending to some destinations costs more than one message. Please see the Price List for details.

The unit attribute is normally messages. In case the payment methodology changes, this unit may also change. If payments and the remaining credits are important to your application, make sure to check that this attribute is set to messages.

The gateway will refuse to accept a message unless there is enough credits for the job.

Example of a request:

GET /credits

Example of a response:

<?xml version="1.0" encoding="utf-8" ?>
<m:User xmlns:m="https://gw1.tel.gigahost.dk" 
    xmlns:xlink="http://www.w3.org/1999/xlink">
    <username>mustermann</username>
    <credits unit="messages">1337</credits>
    <hasPassword>yes</hasPassword>
</m:User>

Request URI

Make a GET request to the following URI, replacing username and password:

https://username:password@gw1.tel.gigahost.dk/credits

Input Variables

None

Return Variables

`username`	The username for which the information is valid.
`credits`	The remaining number of credits, specified in the unit given in the `unit` attribute (normally `messages`)
`hasPassword`	Whether or not the user has an API password set. Possible values are `yes` or `no`.

Sending a Message

Example of a request:

POST /messages

POST variables:

sender=4542031337&recipients=4542001234,4542004321
&message=This%20is%20an%20example&tag=ACME_INDUSTRIES

Example of a response:

<?xml version="1.0" encoding="utf-8" ?>
<m:MessageReceipt  xmlns:m="https://gw1.tel.gigahost.dk" 
xmlns:xlink="http://www.w3.org/1999/xlink">
  <acceptedRecipientCount>2</acceptedRecipientCount>
  <erroneousRecipientCount>0</erroneousRecipientCount>
  <cost unit="messages">2</cost>
  <newBalance unit="messages">1335</newBalance>
  <Message id="1a2b3c4d-a99e-1ee7-4242-314159265358" 
  xlink:href="https://gw1.tel.gigahost.dk/messages/
  1a2b3c4d-a99e-1ee7-4242-314159265358" />
</m:MessageReceipt>

Message Length Overview

Number of message parts	Latin-1	Unicode
1 message part	0-160 characters	0-70 characters
2 message parts	161-306 characters	71-134 characters
3 message parts	307-459 characters	135-201 characters

Request URI

Make a POST request to the following URI, replacing username and password:

https://username:password@gw1.tel.gigahost.dk/messages

Input Variables (must be sent as POST variables)

`sender`	The sender number. For phone numbers, make sure to include the country code. The "+" sign may be excluded.
`recipients`	Comma-separated list of recipients. For the phone numbers, make sure to include the country code. The "+" sign may be excluded.
`message`	The message to be sent. Long messages will be split into several message parts, and may cost more than 1 message to send. If the message contains characters that cannot be expressed in the ISO-8859-1 (latin1) character set, the message will be encoded in Unicode (UCS2). This will result in a shorter possible message length. See the Message Length Overview table for details. The highest possible number of message parts is 3, leaving for a maximum message length of 459 characters for latin1 messages, and 201 characters if the message is encoded with Unicode.
`tag` (optional)	Non-unique alphanumeric string, 1-32 characters (letters a-z/A-Z, dash, underscore, and numbers 0-9 only). This optional string will be stored in the SMS gateway along with the message, and can be used for later retrieval. Afterwards, you can request statistics on sent messages to be grouped by tag, so that you can see the number of messages sent to each tag.

Return Variables

`acceptedRecipientCount`	The number of recipients that were validated and accepted for submission. Note that this is no guarantee of the delivery of the message to these recipients.
`erroneousRecipientCount`	The number of recpients that were invalid that were not accepted for submission. If this is >0, there will also be an `<erroneousRecipients> </erroneousRecipients>` element detailing which of the recipients were erroneous.
`cost`	The total cost for the message batch, in the unit specified in the `unit` attribute (normally `messages`).
`newBalance`	The new balance on the account, after having performed the message delivery job.
`Message`	This resource defines the newly created Message. It contains an `id` attribute with the ID number of the message. This is a UUID-style ID that can later be used to retrieve status information about the message.

Getting Status Info about a Message

Once a message has been sent, it is possible to inquire about its status by looking up the message resource. This allows an application to determine for which recipients the delivery succeeded.

Example of a request:

GET /messages/1a2b3c4d-a99e-1ee7-4242-314159265358

Example of a response:

<?xml version="1.0" encoding="utf-8" ?>
<m:Message xmlns:m="https://gw1.tel.gigahost.dk" 
xmlns:xlink="http://www.w3.org/1999/xlink">
    <id>1a2b3c4d-a99e-1ee7-4242-314159265358</id>
    <senderText>+4542031337</senderText>
    <message>This is a test</message>
    <timeEnqueued>2010-02-08T09:28:26Z</timeEnqueued>
    <MessageRecipients>
        <MessageRecipient number="+4542001234" 
        erroneous="no" timeSent="2010-02-08T09:28:26Z" 
        timeDelivered="2010-02-08T09:28:35Z" 
        xlink:href="https://gw1.tel.gigahost.dk/messages
        /1a2b3c4d-a99e-1ee7-4242-314159265358
        /%2B4542001234" />
        <MessageRecipient number="+4542004321" 
        erroneous="no" timeSent="2010-02-08T09:28:26Z"  
        xlink:href="https://gw1.tel.gigahost.dk/messages
        /1a2b3c4d-a99e-1ee7-4242-314159265358
        /%2B4542004321" />
    </MessageRecipients>
    <tag>ACME_INDUSTRIES</tag>
</m:Message>

Request URI

Make a GET request to the following URI, replacing username, password, and message_id:

https://username:password@gw1.tel.gigahost.dk/messages/message_id

Input Variables (as given in the Request URI)

Message ID	The message ID to be given in the URI is the UUID-style number that is returned after you send a message.

Return Variables

`id`	The ID of the message for which this response is about.
`senderText`	The sender of the message.
`message`	The full contents of the message itself.
`timeEnqueued`	The date and time where the message was sent. Note: All timestamps reference to UTC times.
`messageRecipients`	Array of recipients of this message. Each recipient has the following attributes: The `number` attribute denotes the telephone number of the recipient in question The `erroneous` attribute denotes whether the text message for this recipient was successfully delivered to the telephone systems. The `timeSent` attribute, if present, denotes the point of time when the text message for this recipient was sent to the telephone systems. The `timeDelivered` attribute, if present, denotes the point of time when the text message for this recipient was actually delivered to the phone. Note that the absence of this attribute does not mean that the message was not delivered, because some telecom networks do not support message delivery notifications.
`tag` if present	If you supplied a tag with the message, it will also be included in the info about the message.

Getting Status Info about a Message Recipient

If it is desired to get status information about just a single recipient rather than the whole list, this request can be used. This is useful if a message has many recipients and it is undesirable to download the whole list.

Example of a request:

GET /messages/1a2b3c4d-a99e-1ee7-4242-314159265358/4542001234

Example of a response:

Request URI

Make a GET request to the following URI, replacing username, password, message_id, and number:

https://username:password@gw1.tel.gigahost.dk/messages/message_id/number

Input Variables (as given in the Request URI)

Message ID	The message ID to be given in the URI is the UUID-style number that is returned after you send a message.
Number	The number of the recipient. Should be a recipient of the message in question. The number must include the country code, but the "+" sign may be omitted.

Listing the Sent Messages

To get a list of all messages that were sent from the user account, use this request. The resulting output will be sorted by sending time.

Request URI

Make a GET request to the following URI, replacing username and password:

https://username:password@gw1.tel.gigahost.dk/messages

Listing the Allowed Sender Numbers

You can use several phone numbers as sender numbers. However, they must be verified by the system and belong to the specific user account. Use this request to get a list of sender numbers you are allowed to use.

The output will not be sorted, and can be in any order. It is however guaranteed that the same number will not occur more than once.

Request URI

Make a GET request to the following URI, replacing username and password:

https://username:password@gw1.tel.gigahost.dk/numbers

Verifying a new Sender Number

To verify a new phone number as a valid sender number, two requests must be performed. In the first request, the phone number is supplied and a verification code will then be sent by the system as an SMS message. In the second request, you must supply this verification code.

Request URI for sending the verification code

First, make a POST request to the following URI, replacing username and password:

https://username:password@gw1.tel.gigahost.dk/numbers

Input Variables (must be sent as POST variables)

`number`	The desired sender number to be verified. For phone numbers, make sure to include the country code. The "+" sign may be excluded.

After a code has been sent with the above POST request, it must be verified by using the following PUT request.

Request URI for verifying the number using the received code

Make a PUT request to the following URI, replacing username and password:

https://username:password@gw1.tel.gigahost.dk/numbers

Input Variables (must be sent as PUT variables)

`number`	The desired sender number to be verified. For phone numbers, make sure to include the country code. The "+" sign may be excluded.
`code`	The code that was recevied as an SMS message on the phone.