SMS::CPAGateway - Send an SMS through a gateway using the CPA Gateway protocol


        use SMS::CPAGateway;
        use Data::Dumper qw(Dumper);

        my $sms = SMS::CPAGateway->new(
                # Parameters shown with their defaults
                price => 0,                     # Can also be overriden on a per-message basis
                fromNo => undef,        # Value required at construction time
                key => undef,           # Value required at construction time
                servers => undef,       # Value required at construction time
        if (! $sms->send($PHONENO,$MESSAGE))
                # Some error occurred. All servers failed, it gave up sending.
                your_email_sending_sub(youremail,'Sending message to '.$PHONENO.' failed:'."\n\n".Dumper($sms->errors));
        elsif ($sms->hadError)
                # Some error occurred, but SMS::CPAGateway recovered from it. You can
                # log the errors if you wish, but there is no need to as the SMS
                # was successfully sent.
                # This can happen ie. when the phone number supplied is strange (ie.
                # missing country prefix) or when either of the servers failed. If all
                # servers fail, send() will return false and trigger the above check
                # instead.


This module offers a convenient way of sending an SMS from a Perl program using any server(s) that understand the CPA Gateway protocol version 2, which is the current release of the protocol.

This module and the author are not affiliated with Teletopia interactive in any way.



Constructs a new instance of the class. You can supply any of the attributes listed below in the Attributes section to this method during construction time to initialize them.

The following attributes MUST be supplied at construction time: fromNo, key

send($number,$message,$price = $object->price);

Sends a message. It takes either two or three parameters. $number is the recipient phone number and $message is the text message to send. $price is the price of the message, this parameter is optional and defaults to the value of the price attribute if it is undef.

The recipient phone number must include the direction code.

Usage: $sms->send('+0000000000','Message',0);

This returns true on success and false on failure. See also hadError and errors.


Returns true if an error has occured when sending since this object was instantiated. This does NOT indicate that sending a message, or even the last message, failed. The return value of send() indicates that. An error could for instance be that a single server failed, and that we thus fell back to either of the fallback servers.


Returns an array of error messages.


This is used to set and get the id used for a message. Note than an ID can only be used to send a single message, and if the same ID is attempted to be used for multiple messages, the module will automatically generate a random one instead.

If supplied with a string, sets the id for the next SMS to be sent to the string supplied.

If called without any parameters, returns either of the following:

        - The id that is going to be used to send the first SMS (if you
                have not yet sent any SMS through the instance).
        - The id that was used to send the last SMS sent (as long as you have
                not already set an ID that will be used for the next one
                by calling this method with a string value).



The from number. Must be a number that you are authorized by the server to use.


The price of an SMS. This defaults to 0. This can also be supplied as a parameter to send()


Your authorization key.


The ID that is sent along with the message. If this is not supplied then it will be automatically generated. See the id method.


An arrayref of servers to attempt. The list of servers are provided by the service provider.

Example: [ '', '', '' ]


The module has only been tested with UTF-8-compatible messages.

It doesn't provide any means of recieving SMS messages, as that is simply done by HTTP POST requests to a web server, and there is very little a module can add to that as there are a load of different ways to read parameters, and there is little that has to be done with that data without entering site-specific logic.

Please report any bugs or feature requests to



Eskild Hustvedt, <>


Copyright (C) 2010 by Eskild Hustvedt

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.0 or, at your option, any later version of Perl 5 you may have available.