Skip to main content  
  Easy400   |       IBM System i home   |   RSS feed
Public Source
Main utilities
SMS with Clickatell
5250 utility
Windows utility
Service program
Sample code
CGI support

send SMS MMAIL integration of Clickatell SMS service

Some MMAIL users are asking for some SMS support through MMAIL. Mainly they need to raise partner attention to urgent messages sent via e-mail.

After some investigations we found that Clickatell offers a simple integration into their SMS service. This is why we have added to MMAIL some facilities for interfacing the Clickatel SMS server.

1. A few words about Clickatell 5. Setting up MMAIL databases for Clickatell SMS integration
2. Prerequisites for MMAIL Clickatell SMS support 6. MMAIL commands to send SMS
3. Activating MMAIL Clickatell SMS support 7. SMS log
4. How to start a Clickatell SMS test service 8. Work with SMS from your Internet browser
9. Measuring the delivery time of Clickatell SMS messages
1. A few words about Clickatell
  • They offer a free test service, limited to three given recipients phone numbers, that you have to pre-define.
  • When you migrate your "integration" to production, you may send SMS to any phone number without pre-defining it, and ... you start to pay.

2. Prerequisites for MMAIL Clickatell SMS support
  • At least operating system release V4R1.
  • Scott Klement's library LIBHTTP with service programs HTTPAPIR4 and EXPAT.
  • Optionally utility EZ4WEBSERV.

3. Activating MMAIL Clickatell SMS support To activate MMAIL support for Clickatell SMS, run command MMAIL/CLICKACOMP.
This command
  • Creates the MMAIL programs for Clickatell SMS support
  • Activates SSL services (needed by Clickatell)
4. How to start a Clickatell SMS test service
  • Go to the Clickatell home page.
  • Click the link Register in the top right corner.
  • You receive a page named Create your free account. Fill in the requested data
    • do not miss to enter the phone number of the smart phone you will be using for test
    • take a note of your "Account name" and "password"
    then push the button Register.
  • Check your inbox for an email containing a link to validate your registration. You’ll be able to log in after activation.
  • Press the validation link to receive the Clickatell Login screen, press the Login button.
    You are prompted another Login screen with your credentials: your e-mail address and the password that you did define minutes before.
    Complete the login.
  • You receive a welcome page. Press the Next button.
  • You receive a SMS page. Press the link Get started with Single API for SMS only.
  • You receive a "Details" page. Type your "integration name" (example: BudJones) and "description" (example: My fun). Take the other defaults and press the Next button.
  • You receive a "Features" page. Select One-way messaging and Standard. Press the Next button.
  • On the next page just take the defaults and press the Next button.
  • You receive a "Phone numbers" page stating that "You do not currently have any test phones linked to your account". Forget it and press the Next button.
  • You receive a "Save integration" page. Press the Finish button.
  • You receive a "Create integration" page. Just stop it by clicking the circled X button.
  • You receive a "Get Started with SMS" page made of three sections: 1-Set up you test phones, 2-Create and test a SMS integration, 3-Setup your account.
    Do the following:
    1. In section 2 you will see two "API key" green links.
      These are the keys that will allow your SMS requests to work with Clickatell SMS service.
      • Click the first one.
      • You get a "Details" page. Copy and save this 24 characters API-key.
      • Go back one page and perform the saving of the second 24 characters API-key.
        Then go back again to the previous page.
    2. In section 1 press the button Add test phones.
      You receive a screen that allows to define your test phone
      • Enter the phone number and press button Add phone.
      • A unique validation code is sent to your phone: enter it on the screen.
        (you may add two more test phones. You can do it now, ao at a later time after signing in.
  • You are done and you can leave the Clickatell page.

5. Setting up MMAIL databases for Clickatell SMS integration
A few MMAIL programs have been built to allow IBM i to work as a client in requesting SMS service to Clickatell.
However, to make their use as simple as possible, a number of MMAIL database files have been created and they must be loaded with data in order to make programs work.
All these databases are in library MMAILDATA (which is not affected by subsequent MMAIL releases).
At the time being data loading must be performed via DFU. Specifications follow.
    This file documents the so called "integrations" available for you at Clickatell (usually two "integrations" are made available for test from Clickatell).
    Record fields as follow:
    Integration ID:A numeric sequence number assigned by you as identifier of a Clickatell "integration" Api-key
    T=Test P=Production:Whether the following Clickatell "integration" Api-key is in Test or in Production at Clickatell
    Integration API-key:A 24 char integration" Api-key obtained from Clickatell (Example: V7n2Mgk9SGmpJ0TRotsl5A== )
    Integration name:(Optional) - The name of the "Integration" for this Api-key as registered at Clickatell
    This file documents the pre-registered test phone numbers defined at Clickatell for testing the "integrations" still under test (A maximum of three test phones can be defined at Clickatell for a couple of test "integrations").
    Phone numbers must start with the appropriate country phone code (example: 33 for France).
    Record fields as follow:
    Authorized phone number:A pre-defined phone number used for test
    This file is the SMS Phone Book used by command MMAIL/CLICKATELL to send SMS (see later).
    Record fields as follow:
    Person identifier:A short identifier for a given person (example: myself)
    Person full name:Full name of this person (example: Edith Plaff)
    Phone number:Phone number of this person
    Integr. ID to be used:Integration ID for the Api-key (SEE file CLICKAINT) to be used when sending SMS to this phone number
    Note 1. When the "integration" used for a given phone number is still in test, the phone number must exist in file CLICKAUTHPH.
    Note 2. This SMS Phone Book may also be maintained with the WEB program WRKSMS.

6. MMAIL commands to send SMS
  1. Command  CLICKATELL 
                          Send SMS via Clickatell (CLICKATELL)
     Type choices, press Enter.
     Recipient ID . . . . . . . . . . TO   _________________________________________
     Message to be sent . . . . . . . MSG  _________________________________________
    ____________________________________________________________________ ...
    Command parameters:
    • Recipient ID (TO) - ID of the person that will receive the SMS. This ID must be documented in field "Person identifier" a record of file MMAILDATA/CLICKABOOK. This parameter is case sensitive.
    • Message text (MSG) - The message text to be sent. Up to 700 characters are allowed. This parameter is case sensitive.
  2. Command  CLICKAT2 
                            Send SMS via Clickatell (CLICKAT2)
     Type choices, press Enter.
     Mobile number  . . . . . . . . . TO   _________________________________________
     Message to be sent . . . . . . . MSG  _________________________________________
    ____________________________________________________________________ ...
    Note on command setup. File MMAILDATA/CLICKA2INT must contain a record specifying:
    • 1 in field Integration ID
    • The appropriate Clickatell API_key in field Integration API-key.
    Than can be done using DFU.
    Command parameters:
    • Mobile number (TO) - Destination mobile number, max 20 digits. Characters other than digit are not accepted.
    • Message text (MSG) - The message text to be sent. Up to 700 characters are allowed. This parameter is case sensitive.
Note on commands CLICKATELL and CLICKAT2
The execution of these commands simulates a client HTTP connection to the Clickatell SMS server. The query string of the URL contains the integration Api-key, the destination phone number and the message text.
  • All the parameters are checked by the command validation program.
  • A feeback string is returned from the Clickatell SMS server and reports the result of this SMS request. This string is rendered to a short sentence containing a two characters "OK" if the SMS sending was accepted. This feedback string
    • shows up in a joblog message
    • is stored in the environment variable CLICKATELL_RESPONSE .
      Therefore, if the command is issued from a program and the program needs to know if the SMS request was accepted, the program should just retrieve the environment variable CLICKATELL_RESPONSE and check if the "OK" is there.

7. SMS log
Commands CLICKATELL and CLICKAT2 maintain a log in database file MMAILDATA/CLICKALOG.
The log contains the following information:
  • Date
  • Time
  • SMS status: O (displayed as: OK) if the SMS request was accepted by Clickatell, 1 (displayed as: failed) if the SMS request was rejected by Clickatell.
  • Integration name
  • Integration type: T for test, P for production
  • Destination phone number
  • Name of the phone owner
  • Number of characters in the message text
  • Message text
This log can be displayed by the WEB program WRKSMS (see next).
Note on name of the phone owner - While command CLICKATELL has no problem in knowing and writing to the SMS log the name of the phone owner, command CLICKAT2 has no way to know it unless you make it available as job environment variable MMAIL_SMSFNAME before command CLICKAT2 is run.


8. Work with SMS from your Internet browser
After installing the HTTP instance MMAIL (available in stream file /mmail/conf/httpd.conf),
using the URL http://...:8035/mmailp/wrksms.pgm
you may run the WEB CGI program WRKSMS.
It features the following menu:

Work with SMS
Send SMS
Display SMS log
Phone book
Integration API's

Through this menu you can:
  • Send SMS messages
  • Display the SMS log entries for the last day, week, month, 6 months or year
  • Maintain the SMS phone book
  • Display your Clickatell Integration API-keys.

9. Measuring the delivery time of Clickatell SMS messages
A critical point of your testing with Clickatell SMS integrations is that of measuring the time taken in delivering the SMS messages.
The message delivery system may not be Message delivery may not be steady: some messages could be delivered in one second, some other in a few minutes, some other in hours, and - the worst case - multiple messages could be delivered in a single batch shot.
If you are asking for "time critical SMS", you must make sure that all messages are delivered within 2 seconds.
In order to obtain what you need, you have better contacting the Clickatell support ( providing evidence of the delivery times you are experiencing.
There are a few commands that may help in providing such evidence:

  1. Command TESTSMS
                   Test Clickatell SMS responses (TESTSMS)  
     Type choices, press Enter.                                   
     Recipient ID . . . . . . . . . . TOID                                
     Interval (min.s) between SMS's   INTERVAL  120           15-1440
    Use this command to run a never-ending test on Clickatell SMS delivery response times. This is how it works:
    1. In this command, parameter TOID identifies an entry in the SMS phone book (file MMAILDATA/CLICKABOOK) documenting the phone number of a given person. It is suggested that this destination phone number is that of some personal smart phone of yours.
    2. The command submits a job - named TESTSMS - for batch execution.
    3. This job sends, at a given rate (specified in parameter INTERVAL), SMS messages (via command MMAIL/CLICKATELL) to the specified phone number. Each message contains the date (yyyy-mm-dd) and the time ( when that SMS request was posted. Example:
      "Test message sent on 2019-09-06 at 11.56" .
    4. A log of such SMS requests is maintained in file MMAILDATA/TESTSMSDAT.
    It is then your duty to manually record delivery response times as follow:
    1. Start a DFU on the SMS request log file (MMAILDATA/TESTSMSDAT).
    2. As soon as your smart phone receives a Clickatell SMS, you must update the related SMS request log record (the one posted on the date and time specifed in the message) as follow:
      1. Field Date Received - the date (yyyy-mm-dd) when that message was received
      2. Field Time Received - the time ( when that message was received
      3. Field Sending phone number - The phone number or the ID of the last network phone delivering that SMS message
      4. Field Response time (mm) - Leave it as it is. It will be computed later on by command MMAIL/TESTSMSP.
    You may then use command MMAIL/TESTSMSP at any time to provide a performance report from the SMS request log file (MMAILDATA/TESTSMSDAT).

  2. Command TESTSMSP
                         Report SMS delivery response (TESTSMSP)    
     Type choices, press Enter.                                     
     Date (format yyyymmdd) . . . . .  DATE    *TODAY     yyyymmdd, *TODAY, *ALL
    Use this command to generate a report about performance of the SMS test requests (logged on file MMAILDATA/TESTSMSDAT by command MMAIL/TESTSMS).
    This report is made of two parts:
    • REPORT 1 - by "SENT DATE &TIME" - This part lists the SMS requests by descending SMS request timestamp and provides the delivery time (in minutes) for each SMS. The average delivery time is reported in the bottom line.
    • REPORT 2 - by "SENDING PHONE NUMBER" AND "DELIVERY DATE & TIME" - This part lists the SMS requests by "Last delivering phone number" and SMS "delivery timestamp".
      From this report one can easily find cases where multiple deliveries occurred at the same time. Such cases are not acceptable and should be reported to Clickatell support organization.

Example of performance report
  REPORT 1 - by "SENT DATE &TIME"                                
  REQUEST           DELIVERED        DELIVERY        SENDING              
  DATE       TIME   DATE       TIME  TIME (min.s)    PHONE NUMBER    
  2019-09-06 22.00  2019-09-06 22.00       0         INFOmessage      
  2019-09-06 20.00  2019-09-06 20.01       1         INFOmessage      
  2019-09-06 18.00  2019-09-06 18.00       0         INFOmessage      
  2019-09-06 17.32  2019-09-06 17.32       0         INFOmessage      
  2019-09-06 17.01  2019-09-06 17.01       0         INFOmessage     
  2019-09-06 16.13  2019-09-06 16.14       1         INFOmessage      
  2019-09-06 15.43  2019-09-06 15.44       1         INFOmessage      
  2019-09-06 15.13  2019-09-06 15.13       0         INFOmessage      
  2019-09-06 14.56  2019-09-06 14.56       0         INFOmessage     
  2019-09-06 14.26  2019-09-06 14.26       0         INFOmessage            
  2019-09-06 13.56  2019-09-06 13.56      30         +385 97 6456 129  
  2019-09-06 13.26  2019-09-06 13.26       0         +393 66 3832 764  
  2019-09-06 12.56  2019-09-06 14.15      79         +385 97 6456 130  
  2019-09-06 12.26  2019-09-06 12.54      28         +385 97 6455 997  
  2019-09-06 11.56  2019-09-06 12.16      20         +385 97 6455 989  
  2019-09-06 11.26  2019-09-06 11.31       5         +393 79 1672 585  
  2019-09-06 11.19                  ***NO-DELIVERY               
  2019-09-06 11.10  2019-09-06 12.16      66         +385 97 6455 989  
  2019-09-06 10.40  2019-09-06 12.16      96         +385 97 6455 989  
  2019-09-06 10.10  2019-09-06 11.57     107         +385 97 6463 265  
  2019-09-06 09.40  2019-09-06 11.57     137         +385 97 6463 265  
     AVERAGE DELIVERY TIME:     21 minutes

  SENDING              DELIVERY          REQUEST           DELIVERY    
  PHONE NUMBER         DATE       TIME   DATE       TIME   TIME (min.s)
  +385 97 6455 989     2019-09-06 12.16  2019-09-06 10.40       96     
                                         2019-09-06 11.10       66     
                                         2019-09-06 11.56       20     
  +385 97 6455 997     2019-09-06 12.54  2019-09-06 12.26       28     
  +385 97 6456 129     2019-09-06 13.56  2019-09-06 13.56       30     
  +385 97 6456 130     2019-09-06 14.15  2019-09-06 12.56       79     
  +385 97 6463 265     2019-09-06 11.57  2019-09-06 09.40      137     
                                         2019-09-06 10.10      107     
  +393 66 3832 764     2019-09-06 13.26  2019-09-06 13.26        0     
  +393 79 1672 585     2019-09-06 11.31  2019-09-06 11.26        5     
  INFOmessage          2019-09-06 22.00  2019-09-06 22.00        0     
                                  20.01  2019-09-06 20.00        1     
                                  18.00  2019-09-06 18.00        0     
                                  17.32  2019-09-06 17.32        0     
                                  16.14  2019-09-06 16.13        1     
                                  15.44  2019-09-06 15.43        1     
                                  15.13  2019-09-06 15.13        0     
                                  14.56  2019-09-06 14.56        0     
                                  14.26  2019-09-06 14.26        0     
Data collected on test SMS log file MMAILDATA/TESTSMSDAT:
 entered by command TESTSMS
 manually enter by user via DFU upon SMS message delivery
 computed by command TESTSMSP

Usefullness of this report
  • On September 6, 2019 at hours 9.40 we entered command MMAIL/TESTSMS. In this way we started a non-ending job which was sending an SMS every 30 minutes to out test phone number.
  • The first SMS was sent at 9.40, the second SMS was sent at 10.10.
    Nothing was delivered to our test phone until hours 11.57. At that time, both the first and the second message were delivered by phone number +385 97 6463 265 .
  • The following SMS's behaved more or less the same way (incidentally, one was never delivered).
  • At about noon we raised by e-mail an issue to Clickatell Support, providing the report from command MMAIL/TESTSMSP (a subset of the report above).
  • Things continued that unacceptable way until hours 14.26, when the delivery started being almost immediate.
  • Meanwhile we received an e-mail message from Clickatell support saying that they upgraded their network path to us.
Since then the SMS response time is keeping the same excellent level.