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 Tag

Description

Default

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_date

This is the date the messages must be sent out. Format is dd/MMM/ yyyy eg: 13/apr/2009

*default_time

This 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 / VCARD

SMS

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 Tag

Description

Default

*numto

The number the message must go to.

SMS

*customerid

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

““

senderid

The senderid can be altered (this is the number the message is received from). Only certain accounts allow this feature.

““

time

The time the message must be delivered. This is joined with the default_date. See default_time for formatting.

data1

This is data that will be sent

““

type

This is the default setting for the call but can be overridden by the individual entries.
Values can be SMS / SMSR / VCARD / WPUSH / PORT

SMS

costcentre

Will be used in future.

““

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

Description

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