NAME

Net::SMS::BulkSMS - send SMS messages via provider bulksms.co.uk

SYNOPSIS

 use Net::SMS::BulkSMS;

 my ($sms,$msg,$code,$result_hp,$msg_id,$credits);

 $sms = Net::SMS::BulkSMS->new (username=>"aaaaaaaaaaaa", password=>"bbbbbbbbbbbb", sender => "SomeCoUk");
 or
 $sms = Net::SMS::BulkSMS->new (test => 1, test_form_url => "mycompany.co.uk/cgi-bin/form.pl/");

 ($credits,$code) = $sms->get_credits;
 ($credits,$code) = $sms->quote_sms (message=>"Testing", msisdn=>"44123123456");
 ($credits,$code) = $sms->quote_sms (message=>"Testing", msisdn=>"44123123456", msg_class=>"0");
 ($msg_id,$code) = $sms->send_sms (message=>"Testing 1", msisdn=>"44123123456");
 ($msg_id,$code) = $sms->send_sms (message=>"Testing 2", msisdn=>"44123123456,44567567890");
 ($msg,$code,$result_hp) = $sms->get_report (msg_id=>$msg_id);
 ($msg,$code,$result_hp) = $sms->get_report (msg_id=>$msg_id, msisdn=>"44123123456");

DESCRIPTION

This module provides an SMS transport mechanism for the gateway bulksms.co.uk. You will need to create an account at www.bulksms.co.uk and obtain a username and password, then you can use this module to send and query the status of SMS messages. The transport mechanism is via the HTTP API published at http://www.bulksms.co.uk/docs/eapi/current/.

ABSTRACT

Net::SMS::BulkSMS provides a calling interface and transport to send SMS text messages via the gateway bulksms.co.uk.

CONSTRUCTOR

Create a new BulkSMS object:

$sms = Net::SMS::BulkSMS->new ( [ test => 1, ] username => $username, password => $password, [ sender => $sender, ] [ signature => $signature, ] [ signature_datetime => 0, ] [ max_recipients => $max_recipients, ] [ num_retries => $num_retries ] )

This class method constructs an BulkSMS object. You must either supply a valid username and password for an account at bulksms.co.uk, or set test => 1 and provide test_form_url pointing to a script that will print posted form arguments so you can debug your SMS interface without sending real messages.

The remaining parameters are optional and override built-in defaults.

username password

Valid details for an account at bulksms.co.uk, encoded in base64 MIME::Base64.

test

True/False(default). When true turns on test mode, no messages will be sent, and HTTP requests will be sent to test_form_url instead of bulksms.co.uk's eapi.

sender

Up to 11 alphanumeric characters, either the mobile number to reply to or a company name.

signature

Text to append to each sent message, e.g. "\nAcmeCoUk".

signature_datetime

True(default)/False. Whether to append a date time stamp after signature.

max_recipients

Number, default 200. Maximum number of phone numbers allowed when sending the same message to multiple recipients. Set to 0 for unlimited.

num_retries

Number, default 3. Number of times the transport retries posting HTTP requests before failing.

METHODS

The following methods work with a created BulkSMS object.

get_credits

Fetches the available credit balance on the bulksms account.

Returns

        success: (credits,1) credits is a string representation of credit balance to two floating points
        failure: ("errorcode: errormessage",0)

quote_sms

Parameters

Takes exactly the same parameters as the send_sms method, and quotes how many credits it would take to fulfil the request via send_sms.

Returns

        success: (credits,1) credit is a string representation of number of credits required to send a
message with the specified parameters
        failure: ("errorcode: errormessage",0)

send_sms

Send an SMS message to one or more recipients.

Required parameters message: max 160 chars, 280 for 8bit msisdn: comma separated list of recipient phone numbers

Optional parameters sender: sender id (if alphanumeric, max 11 characters). This facility has to be specifically enabled for your account on request. Alphanumeric sender id is a route-specific feature. msg_class: currently 0 (flash SMS) or 2 (normal SMS), default 2 dca: Data Coding Alphabet: 7bit,8bit or 16bit, default 7bit (normal text message). For 8bit (ringtones,logos) or 16bit (Unicode), a message containing only hexadecimal octets, to a maximum of 280 characters (140 octet pairs), must be submitted. Currently, concatenation is not supported for Unicode messages. 16-bit is a route-specific feature. want_report: 0 or 1, default 1 cost_route: 1 or 2, default 1 (future functionality - always use 1 for now, if used) msg_id: a unique id generated by yourself, to reduce risk of duplicate submissions - future functionality, currently unused.

Returns success: ($msg_id, 1) failure: ("errorcode: errormessage", 0)

        error codes
        0: In progress (a normal message submission, with no error encountered so far). 
        22: Internal fatal error 
        23: Authentication failure 
        24: Data validation failed 
        25: You do not have sufficient credits 
        26: Upstream credits not available 
        27: You have exceeded your daily quota 
        28: Upstream quota exceeded 
        40: Temporarily unavailable 

get_report

Get a status report on a sent message batch by msg_id.

Required parameters msg_id: message id returned from send_sms

Optional parameter msisdn: comma separated list of phone no.s by which to restrict report

Returns failure: ("errorcode: errormessage",1,undef) success: ($msg,0,$result_hash_ptr) $msg is eapi message, $result_hash_ptr is eapi message broken down to a hash of entries by phone no. containing { code, desc } from this table

        0: In progress (a normal message submission, with no error encountered so far). 
        10: Delivered upstream 
        11: Delivered to mobile 
        22: Internal fatal error 
        23: Authentication failure 
        24: Data validation failed 
        25: You do not have sufficient credits 
        26: Upstream credits not available 
        27: You have exceeded your daily quota 
        28: Upstream quota exceeded 
        29: Message sending cancelled 
        30: Test complete (you should never see this) 
        40: Temporarily unavailable 
        50: Delivery failed - generic failure 
        51: Delivery to phone failed 
        52: Delivery to network failed 
        60: Transient upstream failure (transient) 
        61: Upstream status update (transient) 
        62: Upstream cancel failed (transient) 
        70: Unknown upstream status 

SEE ALSO

MIME::Base64

AUTHOR

Net::SMS::BulkSMS was developed by Peter Edwards <peter@dragonstaff.co.uk>.

COPYRIGHT

Copyright 2007 Peter Edwards <peter@dragonstaff.co.uk>.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.