I have a SMS gateway built upon smsd and Huawei-1550 which is being used to receive and forward text messages. Recently I started checking the stats for the account and found that I am not using the whole SMS package I am paying for so I decided to look into alternative ways of sending those messages.

After searching for the gateways that have a public API I decided to try “AtomPark”. It is also known as ePochta and is accessible from a dozen of web sites:

They specialize in Bulk SMS Text Messaging, yes, the messages that are notifying you about some sale or ask you to visit some site may be coming from such kind of company…

Well, I am going to use their gateway for much more useful purpose.

All the examples they have on their docs on API v2.0 and docs on API v3.0 are provided in PHP, I am using Python and I failed to find the examples in any other language.

It turned out that the integration is not that straightforward so I decided to write this blog post to tell about the issues I had while trying to make use of the service.

There are two API versions, first is XML-based and may look simpler but I suggest you to use v3 instead as it generally better.

API v2.0

First of all, the only way you can pass the parameters in v2.0 is through POST request in multipart/form-data format (the one with boundaries and such), the service does not accept the application/x-www-form-urlencoded format but fails to tell you about the problem.

HTTP/1.1 200 OK'
Date: Sat, 04 Aug 2012 12:57:57 GMT
Server: Apache/2.2.19 (FreeBSD) mod_ssl/2.2.19 OpenSSL/0.9.8n DAV/2 PHP/5.3.6
with Suhosin-Patch
X-Powered-By: PHP/5.3.6
Content-Length: 0
Content-Type: text/html

So first of all, write a routine that will encode the “XML” parameter into multipart/form-data. See the example below.

In case you are using ElementTree (or any other library to build the XML) you may start getting a weird response:

<?xml version="1.0" encoding="UTF-8"?>
<RESPONSE>
<status>-2</status>
<credits>0</credits>
</RESPONSE>
</code>

According to the documentation, that means the XML is not valid. After a ton of debugging I found out that the gateway itself is not a good XML parser and fails to parse the document if it is missing newlines. This can be fixed by reformatting the document (found the code in Doug Hellmann’s article).

#!/usr/bin/python # -*- coding: utf-8 -*- # This code is in public domain import httplib2 import urllib import random from xml.etree.ElementTree import Element, SubElement, Comment, tostring from xml.dom import minidom httplib2.debuglevel = 9 USER = '' PASSWORD = '' PHONE_NUMBER = '' GATEWAY_URL = 'https://atompark.com/members/sms/xml.php' sms = Element('SMS') operations = Element('operations') operation = Element('operation') operation.text = 'SEND' operations.append(operation) sms.append(operations) authentification = Element('authentification') username = Element('username') password = Element('password') username.text = USER password.text = PASSWORD authentification.append(username) authentification.append(password) sms.append(authentification) message = Element('message') sender = Element('sender') sender.text='sms-info' text = Element('text') text.text = u'Example Text Message' message.append(sender) message.append(text) sms.append(message) numbers = Element('numbers') number = Element('number') number.text = PHONE_NUMBER numbers.append(number) sms.append(numbers) xml = tostring(sms, encoding='UTF-8') xml = minidom.parseString(xml).toprettyxml(indent=" ") xml = xml.encode('utf-8') boundary = '-' * 21 + str(int(random.random() * 1000)) headers = {'Content-Type': 'multipart/form-data; boundary=%s' % boundary,} body = '--' + boundary + '\r\n' + \ 'Content-Disposition: form-data; name="XML"\r\n\r\n' + \ xml + '\r\n--' + boundary + '--\r\n' client = httplib2.Http() resp, content = client.request(GATEWAY_URL, method='POST', headers=headers, body=body) print "Resp: %s" % (resp, ) print "Content: %s" % (content, )

API v3.0

This version is just a bit more complex at the authentication stage but it works with both types of POST encoding (no need for that boundary) and the response is generated as a JSON document.

The only thing you need to know is that you will have to include version and action parameters too (which seems to be an overkill – the URL already has the version and action embedded).

The signature calculation is straightforward too. It looks like it was modelled after Facebook’s old authentication system.

Here’s the complete example – PUBLIC_KEY and PRIVATE_KEY can be obtained from your settings page at AtomPark member area:

#!/usr/bin/python # -*- coding: utf-8 -*- # This code is in public domain import json import httplib2 import urllib import hashlib PUBLIC_KEY='' PRIVATE_KEY='' PHONE_NUMBER='' ATOMPARK_GATEWAY_URL='http://atompark.com/api/sms/3.0' message = u'This is a Test Message'.encode('utf-8') args = {'sender': 'sms-info', 'text': message, 'phone': PHONE_NUMBER, 'datetime': '', 'sms_lifetime': 0, 'key': PUBLIC_KEY, 'version': '3.0', 'action': 'sendSMS', 'test': 1 } sig_base_string = ''.join([ str(args[v]) for v in sorted(args.keys()) ]) sig_base_string += PRIVATE_KEY sig = hashlib.md5(sig_base_string).hexdigest() args['sum'] = sig client = httplib2.Http() headers = {'Content-Type': 'application/x-www-form-urlencoded'} body = urllib.urlencode(args) resp, content = client.request(ATOMPARK_GATEWAY_URL + '/sendSMS', method='POST', headers=headers, body=body) print resp print content

That code can be seen as a starting point. Their rates for Ukrainian numbers are 0.14₴ (about $0.018) and that makes it a perfect service to send the notification messages from.

while not keypressed

Sending text messages using AtomPark API

API v2.0

API v3.0