ResourcesAPI documentation

mailkit.sendsms

SMS campaign delivery

XML-RPC request must be sent in the format displayed below. 

NOTICE: Data must be Base64 encoded.

API call example:

XML

<?xml version="1.0" encoding="UTF-8"?>
<methodCall>
  <methodName>mailkit.sendsms</methodName>
  <params>
    <param>
    <value>
      <int>client_id</int>
    </value>
    </param>
    <param>
    <value>
      <string>client_md5</string>
    </value>
    </param>
    <param>
    <value>
      <struct>
        <member>
          <name>ID_message</name>
          <value>
            <i4>123456</i4>
          </value>
        </member>
        <member>
          <name>ID_user_list</name>
          <value>
            <i4>123456</i4>
          </value>
        </member>
        <member>
          <name>use_utf</name>
          <value>
            <string>FALSE</string>
          </value>
        </member>
        <member>
          <name>allow_split</name>
          <value>
            <string>FALSE</string>
          </value>
        </member>
        <member>
          <name>source</name>
          <value>
            <string>Sendername</string>
          </value>
        </member>
      </struct>
    </value>
    </param>
    
------- recipient -------
    
    <param>
    <value>
      <struct>
        <member>
          <name>mobile</name>
          <value>
            <i4>+420778535877</i4>
          </value>
        </member>	  
        <member>
          <name>email</name>
          <value>
            <string>mail@example.com</string>
          </value>
        </member>
		<member>
          <name>first_name</name>
          <value>
            <string>First name</string>
          </value>
        </member>
        <member>
            <name>gender</name>
            <value>
              <string>F</string>
            </value>
        </member>
        <member>
          <name>custom1</name>
          <value>
            <i4>123</i4>
          </value>
        </member>
        <member>
          <name>custom2</name>
          <value>
             <string>custom field</string>
          </value>
        </member>
      </struct>
    </value>
    </param>
    
------- content -------
    
    <param>
    <value>
    <struct>
    <member>
      <name>sms_data</name>
      <value>
        <string>base64 encoded sms content</string>
      </value>
    </member>
    <member>
      <name>content</name>
      <value>
        <struct>
          <member>
            <name>VAR1</name>
            <value>
              <string>base64 data</string>
            </value>
          </member>
          <member>
            <name>VAR2</name>
            <value>
              <string>base64 data</string>
            </value>
          </member>
          <member>
            <name>VAR_GROUP</name>
            <value>
              <array>
                <data>
                  <value>
                    <struct>
                      <member>
                        <name>VAR1a</name>
                        <value>
                          <string>base64 data</string>
                        </value>
                      </member>
                      <member>
                        <name>VAR1b</name>
                        <value>
                          <string>base64 data</string>
                        </value>
                      </member>
                    </struct>
                  </value>
                  <value>
                    <struct>
                      <member>
                        <name>VAR2a</name>
                        <value>
                          <string>base64 data</string>
                        </value>
                      </member>
                      <member>
                        <name>VAR2b</name>
                        <value>
                          <string>base64 data</string>
                        </value>
                      </member>
                    </struct>
                  </value>
                </data>
              </array>
            </value>
          </member>
        </struct>
      </value>
    </member>
    </struct>
    </value>
    </param>
  
--------------
 
 </params>
</methodCall>
		

Structured

my $result = $server->call(
    'mailkit.sendsms',
    $cid,
    $md5,
    {
        'ID_user_list' => $ID_user_list,
        'ID_message'   => $ID_message,
        'use_utf'      => 'TRUE',
        'allow_split'	=> 'FALSE'
        'source'	=> 'Sendername',
    },
    {
        'email'        => $email,
        'mobile'       => $mobile,
        'custom1'      => 1,
        'custom2'      => 2,
        'custom3'      => 3,
    },
    {
        'sms_data'     => encode_base64("sms message content"),
        'content',
        {
            'company_rpc',encode_base64('Mailkit'),
            'name_rpc',encode_base64('sample name'),
            'test_url',encode_base64('http://www.example.com'),
        },
    },
);

Values

client_id * = client ID can be found in your Mailkit account's menu Profile / Integration / API settings.

client_md5 * = MD5 code can be found in your Mailkit account's menu Profile / Integration / API settings.

id_message * = ID of SMS campaign

id_user_list * = ID of mailing list, where will be the recipient added

use_utf  = allow UTF8 characters in SMS. Can be one of:

  • FALSE (default) = all UTF8 characters will be converted to ASCII (no non-ASCII characters will be in the resulting message)
  • TRUE = UTF8 characters are allowed in SMS (messages with such special characters are limited to 70 characters and any longer message will be split into multiple messages during delivery)

allow_split  = allows long SMS messages to be split to multiple parts (max. 6). Can be one of:

  • FALSE (default) = SMS will not be split
  • TRUE = SMS longer than 160 characters will be split into multiple parts

source = sender name also known as SenderID (optional). This name will be displayed on recipient's device as the sender instead of the number. Sender name/SenderID needs to be pre-approved by telco operators and availability varies by destination country and network.

mobile * = mobile phone in international format (+420XXXYYYXXX)

email = e-mail address of the recipient (optional) - if not provided, system will automatically create a recipient record in the form of +420XXXYYYXXX@mailkit.mobile.

Keep in mind that only e-mail address is the default identificator of each recipient. If an SMS recipient is added without an e-mail at first and with e-mail the second time it will produce two distinct records with no relation to each other.

first_name,
gender,
custom1, ...
 = custom recipient data

sms_data (base64 data) = SMS content encoded using base64

content (base64 data) = variables encoded using base64. Variable can be later used in templates under the names used in the API call.

* required value

Successful call response:

XML

<?xml version="1.0" encoding="utf-8"?>
<methodResponse>
  <params>
    <param>
      <value>
        <struct>
		  <member>
            <name>data</name>
            <value>
              <i4>12345678</i4>
            </value>
          </member>
		  <member>
            <name>data2</name>
            <value>
              <i4>12345</i4>
            </value>
          </member>
          <member>
            <name>data3</name>
            <value>
              <i4>12345678</i4>
            </value>
          </member>
          <member>
            <name>status</name>
            <value>
              <i4>0</i4>
            </value>
          </member>
        </struct>
      </value>
    </param>
  </params>
</methodResponse>

Values

data = ID of newly created or matched recipient

data2 = ID of sent message

data3 = ID of campaign

status

  • 0 = update (recipient has been updated)
  • 1 = insert (recipient has been inserted)
  • 2 = insert (recipient has been previously unsubscribed and remains unsubscribed)
  • 3 = update (recipient has been previously unsubscribed and remains unsubscribed)
  • 4 = fault (mobile phone had an invalid format and recipient was not inserted)