NAME

Mojar::Message::BulkSms - Send SMS via BulkSMS services.

SYNOPSIS

  use Mojar::Message::BulkSms;
  my $sms = Mojar::Message::BulkSms->new(username => ..., password => ...);

  # Synchronous
  $sms->message(q{Team, have we used up all our credits yet?}),
      ->send(recipient => '0776 432 111')
      ->send(recipient => '0778 888 123');

  # Asynchronous
  my @error;
  $sms->message(q{Team, please check the async responses}),
      ->send(recipient => $recipient[0] => sub { $error[0] = $_[1] })
      ->send(recipient => $recipient[1] => sub { $error[1] = $_[1] });

DESCRIPTION

Sends SMS messages via BulkSMS services such as usa.bulksms.com and bulksms.de.

ATTRIBUTES

• protocol

    $sms->protocol;  # defaults to http
    $sms->protocol('https');

• address

    $sms->address;  # defaults to www.bulksms.co.uk
    $sms->address('bulksms.de');

• port

    $sms->port;  # defaults to 5567
    $sms->port(5567);

• path

    $sms->path;  # defaults to eapi/submission/send_sms/2/2.0
    $sms->path('eapi/submission/send_sms/2/2.1');

• gateway

    $sms->log->debug('Using gateway: '. $sms->gateway);

  The full URL constructed from the parts above.

• username

    say $sms->username;
    $sms->username('us3r');

  Username for the account.

• password

    say $sms->password;
    $sms->password('s3cr3t');

  Password for the account;

• recipient

    say $sms->recipient;
    $sms->recipient('077-6640 2921');

• sender

    say $sms->sender;
    $sms->sender('Your car');

  The SMS sender. However, in my (UK) experience this has no effect.

• international_prefix

    say $sms->international_prefix;  # defaults to 44
    $sms->international_prefix('33');

• message

    say $sms->message;
    $sms->message('Sorry, forgotten what I wanted to say now!');

  The message to send. Bear in mind that unaccepted characters get substituted by the SMS service (often to '?').

• log

    $sms->log($app->log);
    $sms->log(Mojar::Log->new(path => 'log/sms.log', level => 'info'));
    $sms->log->error('Uh-oh!');

  A Mojo::Log-compatible log object. Defaults to using STDERR.

METHODS

new

  $sms = Mojar::Message::BulkSms->new(username => ..., password => ..., ...);

Constructor for the SMS agent.

send

  $sent = $sms->send;

Sends an SMS message. Returns a false value upon failure (when used synchronously).

  $sent = $sms->message('Boo')->send(recipient => $r1)->send(recipient => $r2);

  $sent = $sms->recipient($r3)->send(message => $m1)->send(message => $m2);

Supports method chaining, and will bail-out at the first failure if no callback is given.

  $sms->send(sub {
    my ($agent, $error) = @_;
    ...
  });

  $sms->send(message => 'Stuff' => sub { ++$error_count if $_[1] });

Also supports asynchronous calls when provided a callback as the final argument.

other methods

See the source code for other methods you can override when subclassing this.

REFERENCE

http://www.bulksms.co.uk/docs/eapi/ shows the service API.

CONFIGURATION AND ENVIRONMENT

You need to create an account at www.bulksms.co.uk.

SUPPORT

See Mojar.

DIAGNOSTICS

You can get behind-the-scenes debugging info by setting

  MOJAR_SMS_DEBUG=1

in your script's environment. You should then see all the messages to and from bulksms.co.uk as well as some progress notes.

SEE ALSO

Net::SMS::BulkSMS is similar but blocking.