.\" Copyright (c) 2002-2005, Nadav Har'El
.TH sendsms 1 "29 March 2005"
.SH NAME
sendsms \- send short messages to any Israeli cellphone
.SH SYNOPSIS
.B sendsms
[
.B \-lh
]
[
.BI \-f\  configfile
]
.\".BI [\| file\|.\|.\|. \|]
.I phonenum
.I sender
.I message
.SH DESCRIPTION
.B sendsms
can send SMSs (short messages) to any Israeli cellular phone. All 4 Israeli
providers are supported: Cellcom, Orange (Partner), Pelephone, and Amigo
(Mirs).

.B Sendsms
does the actual sending by connecting to the providers'
SMS-sending websites. As such, sendsms can only work on an Internet-connected
machine (it can optionally use an http proxy). Also, when
.B sendsms 
reports the message was "sent successfully" this only means that the
provider acknowledged receiving the message - the message might be held up
for some time in the provider's queues, or even lost, before arriving to
the recipient. So don't use sendsms for time-critical or life-and-death
messages. That being said, some providers' SMS service is very efficient:
in Cellcom, for example, it rarely takes more than 5 seconds for the message
to arrive to the recipient.

English and Hebrew (ISO-8859-8 encoding, Logical order) messages are supported for
all providers, but not all phones in all providers support receiving Hebrew SMSs.
Note that some very old phones might not be able to receive SMSs at all.

.SH OPTIONS
.TP 10
.I phonenum
The phone number to which to send the SMS. Currently, both old-style and
new-style (2004) numbers are accepted. Old-style numbers must begin with:

   Cellcom:   052, 053, 058, 064 or 065
   Orange:    054, 055, 066 or 067
   Pelephone: 050, 051, 056 or 068
   Amigo:     057

followed by exactly 6 digits. New-style numbers begin with 050, 052, 054,
or 057, followed by 7 digits. Spaces and hyphens are ignored.
An
.I alias
can also be used in place of a phone number: see CONFIGURATION below.

.TP
.I sender
This string is passed to the provider as the "sender" of the message.
It is typically your name, your phone number, or some other identifying
string. It is guaranteed that the sender string will be shown to the
recipient (unless there is some error or the message is too long), but
exactly how it is shown depends on the provider. For example, on Cellcom
the sender string is shown in parentheses after the message itself.

.TP
.I message
This is the actual message to send.

Messages are limited in length,
usually to slightly less than 140 characters. Sometimes the total length
of the message and the sender is limited, and the limit might also depend
on the message's language. All this depends on the specific provider;
Sendsms tries to warn the user when the message is too long (and truncates
the message), but watch out for long messages. Utilities that plan to send
very long messages (e.g., whole email messages) must plan to make several
separate calls to
.BR sendsms ,
because
.B sendsms
does not split a long message.

.TP
.BR \-l , \-h
As
.B sendsms
was written for Israeli cellphones, it naturally needs to support sending
Hebrew messages. By default, or if the
.B -h
option is used, messages that contain non-ASCII characters are assumed
to be in Hebrew, in the so-called ISO-8859-8-i encoding (logical order).
If the
.B -l
option is given, non-ASCII characters are assumed to be Latin1 characters.

If the message is entirely ASCII (e.g., an English message), the -l/-h
options do not make a difference, and every phone (that supports SMSs, of
course) is guaranteed to display it correctly.

Not all provider/phone combinations support Hebrew at all, and some support
Hebrew but do not support Latin1. But some do support both - e.g., Nokia 5120 on
Orange (its non-Hebrew encoding isn't exactly Latin1, but many important
accented Latin characters are the same).

This version does not currently support other encodings or other languages. 

.TP
.B \-u
In this version this option does nothing.

Previously, Cellcom allowed 1 ("Normal"), 2 ("Urgent") or 3 ("Emergency") messages.
Emergency messages, for example get listed on the phone as "new emergency
message", and so on. This option doesn't seem to have other effects - for
example an "Emergency" message does not seem to arrive more quickly than
a "Normal" messageed

.SH CONFIGURATION
Before using sendsms, you must create a configuration file. On Unix-like
systems, it is ".sendsmsrc" in your home directory. On Microsoft Windows with
ActiveState Perl, it is $HOMEDRIVE$HOMEPATH\\sendsmsrc instead. You can
also specify a different configuration file, using the "-f" option.

Most importantly, if you want to send messages to any of the four providers
that
.B sendsms
supports, you must get "accounts" and put the details of these
accounts in your configuration file. Online providers of SMS service
require you to register at their site for such an account.

All these accounts are free (and let you send SMSs for free), but sendsms
provides NO GUARANTEES that these accounts will work or that you will not
be billed later - such accounts are basically agreements between you and
the company you got such an account from, and sendsms or its authors will
not be a party in this agreement and will not be held liable for any of
its consequences.

Register and get accounts in the following sites (some of them are Hebrew-only,
unfortunately, and the Orange site seems to be friendly only to the MS-IE
browser):

 Amigo:
   http://www.amigo.co.il/html/login/new_user.asp
 Cellcom, Pelephone or Orange:
   http://icq.com/sms/login
   (note that if you already have an ICQ number, you can use it, and don't need to register again)
 Orange:
   www.orange.co.il/default.asp?page=/registration/main.asp

An important note on choosing between an ICQ account and Orange's official
account for sending messages to Orange phones: For this provider's official
SMS sending site, you're required to own their phone to complete the
registration for an online SMS sending account. This means two things:

First, if you do not own a phone from Orange you cannot
send SMSs to Orange phones.

The second issue with the official site is that since Orange can "prove" who
sent a message and connect it to your phone bill, they may decide some
time in the future to start charging for these messages. In fact, Orange
charged for this service for a few weeks (10 agorot per message) before
they decided to make the first 20 messages per day free. Sendsms tries
to verify that sending a message is still free (by looking at the text
of the SMS sending pages), but NO GUARANTEE IS MADE by me that your phone
bill does not get charged for the messages you send with sendsms. I
repeat: Orange may charge your phone bill for SMSs you send and sendsms
cannot and will not guarantee that this never happens.

For these reasons, if both Orange and ICQ accounts are configured, the
latter is used for sending messages to Orange.

After getting the accounts, put in ~/.sendsmsrc the directives
    account amigo USER PASSWORD
    account orange USER PASSWORD
    account icq NUMBER PASSWORD (or email instead of number)

using the accounts you acquired above. If you do not do that for a
particular company, you won't be able to send SMSs to numbers in that
company. You may have more than one account for
each provider - in that case one of the accounts is chosen at random on
every invocation of sendsms (the reason you might want to have more than
one account is that most providers limit each account to 20 messages per
day).

Aliases for phone numbers may be defined in your ~/.sendsmsrc using directives
like
       alias mrsmith 053-123456

then "sendsms mrsmith sender message" does the same as "sendsms 053-123456 sender
message".

An "include filename" directive in your configuration file will cause sendsms
to also read the contents of another configuration file (included files might
even include other files, and so on). This is useful, for example, if you
want to have a separate alias file with "alias" commands.

The "http_proxy" configuration directive is used to tell sendsms which proxy
(if any) it should use for making the HTTP connections to the providers' sites.
If no "http_proxy" directive is given, the environment variables http_proxy
and no_proxy are used to choose a proxy (if any). If a "http_proxy none"
directive is given, a proxy is not used (regardless of the environment
variables set). Otherwise, a directive like "http_proxy http://proxy.com:8080/"
sets an http proxy. The directive "proxy ..." is a shortcut for "http_proxy ...".

.SH EXAMPLES
Sendsms can be used to send personal messages to friends in Israel with
cellphone. For example,

    sendsms 050-123456 "John Doe" "Please call me!"

will will send the message "Please call me!" to your friend at 050-123456.
"John Doe" is your name, as will be reported to your friend - you can use
your phone number instead.

Another typical use of sendsms is to send
.B yourself
messages which are generated automatically by a computer. For example,
people have written programs which report to them when emails arrive,
when their bank account situation changes, or send them daily stock quotes.

Remember that you must follow the "terms of service" you accepted when 
you got the providers' SMS accounts. In particular, you must not send
messages to others to disturb them intentionally. Please do not send messages
to random numbers for "testing" sendsms - real people might be getting these
messages.
\fBYou must not use sendsms for mass distribution of unsolicited messages\fR
(like commercial or political advertisements)
as this is both a violation of sendsms's license and a violation of all
SMS providers' terms-of-service.

.SH "EXIT STATUS"
The following exit values are returned:
.TP 4
.B 0
Message was sent successfully. This does not mean that the message has
arrived yet at the recipient's phone, or that it ever will (see
DESCRIPTION above).
.TP
.B >0
An error occurred.
.SH "AUTHOR"
Written by Nadav Har'El, http://nadav.harel.org.il.

Portions of the code have been written by Dan Kenigsberg and Alon Altman,
and many others contributed ideas and small fixes.

Please send bug reports and comments to nyh@math.technion.ac.il.
The latest version is available in http://nadav.harel.org.il/software/sendsms.
.SH "LICENSE"
This is free software, licensed under the GNU General Public License (GPL)
\fBwith the exception\fR that this script may not be used for the
purpose of mass unsolicited message distribution (spam).

In particular, there is NO warranty. Messages you send with sendsms might
arrive corrupted or not arrive at all, might be suddenly charged-for by
your provider or otherwise mess up your life or your business - so please
don't have your lawyers hound me for that.
.SH "SEE ALSO"
.BR perl (1),
.BR LWP (1)