Sending Messages (HTTP XML)

The API supports XML and Parameter based sending.

1. XML

Sending messages is relatively easy, but due to the various options it can seem confusing.
In a nutshell: If you specify a default then it will only be utilized if the entry data does not exist. If neither exists then it will throw an error.

The function accepts 4 parameters
• Type (string) = “send”
• Username (string)
• Password (string)
• XMLData (string)

Example string:
https://mymobileapi.com/api5/http5.aspx?type=send&username=xxx&password=yyy&xmldata=zzz

The XML object looks like this:

<senddata>
    <settings>
        <live>True</live>
        <return_credits>True</return_credits>
        <return_msgs_credits_used>True</return_msgs_credits_used>
        <return_msgs_success_count>True</return_msgs_success_count>
        <return_msgs_failed_count>True</return_msgs_failed_count>
        <return_entries_success_status>True</return_entries_success_status>
        <return_entries_failed_status>True</return_entries_failed_status>
        <default_senderid/>
        <default_date>01/Jan/2018</default_date>
        <default_time>11:15</default_time>
        <default_curdate>01/Jan/2018</default_curdate>
        <default_curtime>12:00</default_curtime>
        <default_data1>This is a default msg</default_data1>
        <default_data2/>
        <default_flash>False</default_flash>
        <default_type>SMS</default_type>
        <default_costcentre>NA</default_costcentre
        <mo_forwardemail>[email protected]</mo_forwardemail>
        <default_validityperiod>24</default_validityperiod>
    </settings>
        <entries>
            <numto>082*******</numto>
            <customerid>UnqiueValue1</customerid>
            <senderid>Test me</senderid>
            <time>12:00</time>
            <data1>This is a test message 1!</data1>
            <data2/>
            <flash>False</flash>
            <type>SMS</type>
            <costcentre>NA</costcentre>
            <validityperiod>48</validityperiod>
        </entries>
</senddata>

XML Tag Table

The following table determines how the result of each XML tag is formatted as well as defines the defaults.

XML TagDescriptionDefault
live If Live = false then it will return the result but won’t send the message.True
return_credits If True then the current Credits count will be returned.False
returnmsgs
credits_used
If True then the amount of credits used will be returned.False
returnmsgs_success
count
If True then the total success data count will appear in the result.False
returnmsgs_failed count If True then the total failed data count will appear in the result.False
returnentires_success status If True then the data that is accepted will be returned in the result.False
default_senderid This is the default setting for the call but can be overridden by the individual entries. Only certain accounts can alter this.Repliable
*default_dateThis is the date the messages must be sent out. Format is dd/MMM/ yyyy eg: 13/apr/2009-
*default_timeThis is the time the messages must be sent out. Format is HH:mm eg: 17:34-
default_curdate This is the current date on your server. It is used to determine when your messages should go out. If not used then the server date is used.Server Date
default_curtime This is the current time on your server. It is used to determine when your messages should go out. If not used then the server time is used.Server time
default_data1 This is the default setting for the call but can be overridden by the individual entries.““
default_flash This is the default setting for the call but can be overridden by the individual entries.False
default_type This is the default setting for the call but can be overridden by the individual entries. Values can be SMS / SMSR / WPUSH / VCARDSMS
default_costcentre Will be used in future.““
mo_forwardemail All incoming replies will be forwarded to this email address““
default_validityperiod The amount of time in hours an SMS should remain valid. The network will continue to try to deliver the SMS over the validity period.

🚧

Post Paid Customers

Return Credits will always return a value of 1000000 on Post Paid accounts as no credit deduction occurs on this account type.

🚧

All entries marked with * are mandatory

For each entry in the XML the following can be utilised:

XML TagDescriptionDefault
*numtoThe number the message must go to.SMS
*customeridThe customerid is a field that is populated that has meaning to your system. This field can be returned in the result sets and can make updating data very easy. We suggest using a GUID or Identity key.““
senderidThe senderid can be altered (this is the number the message is received from). Only certain accounts allow this feature.““
timeThe time the message must be delivered. This is joined with the default_date. See default_time for formatting.-
data1This is data that will be sent““
typeThis is the default setting for the call but can be overridden by the individual entries.
Values can be SMS / SMSR / VCARD / WPUSH / PORT
SMS
costcentreWill be used in future.““
validityperiodThe amount of time in hours an SMS should remain valid. The network will continue to try to deliver the SMS over the validity period. This value will override the ‘default_validityperiod’ setting.-

🚧

All entries marked with * are mandatory

The output of the following will be defined by the input of the above parameters:

<api_result>
    <entries_failed>
        <numto/>
        <customerid/>
        <reason>numto invalid</reason>
        </entries_failed>
        <entries_success>
        <numto>2782*******</numto>
        <customerid>UnqiueValue1</customerid>
        </entries_success>
        <entries_success>
        <numto>2782*******</numto>
        <customerid>UnqiueValue1</customerid>
    </entries_success>
    <entries_success>
        <numto>27832297941</numto>
        <customerid>example</customerid>
    </entries_success>
    <send_info>
        <eventid>27105067</eventid>
        <credits>39763</credits>
        <msgs_credits_used>3</msgs_credits_used>
        <msgs_success>3</msgs_success>
        <msgs_failed>1</msgs_failed>
    </send_info>
    <call_result>
        <result>True</result>
        <error/>
    </call_result>
</api_result>
XML TagDescription
entries_failed If this tag exists then some of the data you pushed has errors.

It will contain: “numto”, “customerid” and “reason”. The reason will be:
numto invalid
senderid invalid
time invalid
flash invalid
costcentre invalid
type invalid
data1 invalid
data2 invalid
* data1 + data2 invalid
entries_success If this tag exists then it will contain “numto” and “customerid”.
send_info This describes the overall data returned. It WILL contain “eventid” and COULD have “credits”, “msgs_credits_used”, “msgs_success” and “msgs_failed”.
credits = credits remaining in account
msgs_credits_used = the amount of credits used
msgs_success = a count of the messages accepted for delivery
msgs_failed = a count of the messages rejected