python-fullsms /

Filename Size Date modified Message
11.6 KB
27.4 KB
10 B
2.6 KB


Send SMS from the command line.

A library and command line interface to the HTTP interface of

Note: this script makes use of Avery Pennarun's excellent (blog post).

Note: If you do not already have an account on, please consider using the following link to register. This will credit the account of the author of python-fullsms with 15,00 €.


If you just want to get started ASAP, follow the instructions below. If you run into trouble contact the author by email or via irc (esc on freenode).

  • Make an account on <-- use this link please.

  • Obtain the script

    • Either clone the git repository with:

      $ git clone git://
    • Or do:

      $ wget
      $ cp sms && chmod +x sms
  • Create a file .fullsms in your $HOME directory which looks like:

    user      = MaxMusterman
    password  = maxmustermangeheim
    sender    = 0049123456789

    ... and substitute the values user and password with your credentials, and sender with the phone number you would like to have the SMS appear to come from.

  • Activate the HTTP-Interface for your account and configure IPs if you want.

  • Start sending SMS:

    $ ./sms send -r 004901234567 "I really enjoy sending SMS from the command line"

    ... you have 0,50 € to try it out. If you like the service, buy some credits and continue to enjoy sending SMS from the command line.

  • Read the rest of this documentation to learn more about options for sending and for managing your phonebook. Documentation

There are two PDFs provided by which describe both the HTTP interface and the available gateways.


There are three subcommands pb to print the phonebook, check to check the account balance and send to send SMS:

$ sms [GENERAL-OPTIONS] < check | send | pb > [SPECIFIC-OPTIONS]

The specific invocations are:

$ sms -h
$ sms -v
$ sms [ -q | -d ] [ -y ] [ -c <config> ] check
      [ -u <user> ] [ -p <password> ]
$ sms [ -q | -d ] [ -y ] [ -c <config> ] send
      [ -u <user> ] [ -p <password> ]
      [ -g <gateway> ] [ -r <receiver> ] [ -s <sender> ]
      [ -p <phonebook> ] [ -e ] [ -i ]
      [ <message> ]
$ sms [ -q | -d ] [ -y ] [ -c <config> ] pb

Because of the way works, the general program options and subcommand options can be mixed and can be placed before or after the subcommand itself. Also, options which are relevant only for send can be given when using check or pb and will be silently ignored.

Command Line Options

Descriptive options :

-h, --help Display help and exit
-v, --version Display version number and exit.

General program options :

-q, --quiet Silence all output. Useful when executing the script from a cronjob.
-d, --debug Activate debugging. Will output noisily what is being done.
-y, --dry-run Don't perform any REST calls. Useful in combination with [-d | --debug].
-c, --config <config>
 The config file to use (default ~/.fullsms). Useful if you have multiple configurations.

For send and check subcommands :

-u, --user <user>
 The username.
-p, --password <password>
 The password.

For check only:

-a, --amount Output only the amount, no fluff.

For send only :

-g, --gateway <gateway>
 The gateway to use (default 22). has multiple ones available
-r, --receiver <receiver>
 The person to send the message to.
-s, --sender <sender>
 The sender to use. Can be 11 alphanumeric or 15 numeric characters.

Phonebook management :

-b, --phonebook <phonebook>
 The phonebook file (default: ~/.fullsms-book). See below for details about this file.
-e, --expand Expand sender from the phonebook. This means, that if the sender name is found in the phonebook, the corresponding number will be used as a sender.
-i, --ignore Ignore errors when expanding receiver. The most common use case is to send messages to people in your phonebook. To avoid typos, the script will abort if the given receiver is not in your phone book. This option disables this behaviour. If you wish to disable this default, consider using the config file.

Note: since [-e | --expand], [-i | --ignore] and [-a | --amount] can also be specified in the config file, you may need a way to revert these if they are set to true. Courtesy of we have the negation options --no-expand, --no-ignore and --no-amount at no additional cost which will do exactly that.

Config File

python-fullsms can be configured using a config file, usually located at ~/.fullsms and whose syntax is a common INI file and contains a single settings section. The most common use case is to save the user, password and sender settings. This way, you need to specify only the receiver and the message on the command line.

The settings given in the config file take precedence over the default values. Whereas the options given on the command line always take precedence over those given in the config file. Using the [-d | --debug] options shows exactly which settings where obtained from where and which ones took precedence.

The following settings are supported in the config file which correspond directly to their command line counterparts:

  • user
  • password
  • gateway
  • receiver
  • sender
  • phonebook
  • expand
  • ignore
  • amount

The three settings expand, ignore and amount are booleans and must take either the value true or false (or any semantically reasonable or case insensitive equivalent). All others are strings.


user      = MaxMusterman
password  = maxmustermangeheim
gateway   = 11
receiver  = 0123456789
sender    = 0123456789
phonebook = ~/.mybook
expand    = true
ignore    = true

Reminder: If you wish to use an alternative file, use the [-c | --config] option.


A rudimentary phonebook file is supported. By default, the script searches ~/.fullsms-book for entries in a section titled contacts:

max = 0123456789
maxine = 1234567890
maximilian = 2345678901

Thus you can use these defined aliases on the command line, see below for examples. If you want to use a different file, use either the phonebook option in the config file or the [-b | --phonebook] command line option.

Example Command Line Usage

The following examples make the assumption that a correct user and password are stored in the config file (see above) and that a phonebook with appropriate entries has been defined.

In the simplest case, only a receiver and message are required:

$ sms send -r maxine "Hello honey, I'm home"

In this case the phone number of maxine will be looked up in the phonebook and expanded. If no such entry exists, the execution will be aborted in order to save you from typos. If you wish to supply the phone number on the command line, you need to use the [-i | --ignore] option, which will ignore any errors caused by numbers not in the phone book:

$ sms send -i -r 0123456789 "Hello honey, I'm home"

If you wish to make this the default behaviour, set ignore to true in your config file.

Using the [-e | --expand] command-line option to expand the sender from the phonebook too, the following will send a message to maxine looking like it came from maximilian:

$ sms send -r maxine -e -s maximilian "Any plans for tonight?"

Because the sender can be either 11 alphanumeric or 15 numeric characters, you need to enable expansion explicitly. Again, If you wish to make this the default behaviour, set expand to true in your config file. Lastly, note that setting an arbitrary sender may or may not be supported by the gateway, see the documentation for details.

The <message> is optional, since the send subcommand also accepts input on stdin, for example by using a UNIX pipe:

$ echo "Any plans for tonight?" | sms send -r maxine

Or, if you don't supply something, the script will wait for input, which you can terminate by sending EOF (ctrl+d):

$ sms send -r maxine
Any plans for tonight? <ctrl+d>

There is also the check subcommand to check account balance:

$ sms check
The current balance for the account 'MaxMusterman' is: 12,571 €

If you want only the amount, use the [-a | --amount] switch or the corresponding config file setting:

$ sms check -a

And finally, a pb subcommand to print the phonebook:

$ sms pb
max           : 0123456789
maximilian    : 2345678901
maxine        : 1234567890

By convetion, a [-h | --help] option is provided:

$ sms -h

Example Library Usage

The python-fullsms can easily be used as a python module:

>>> import fullsms
>>> fullsms.send(user=MaxMusterman,
                 message="Hello honey, I'm home")
(200 : 'OK')

>>> fullsms.check(user=MaxMusterman, password=maxmustermangeheim)
(200, '12,571')


  • Use BeautifulSoup to get the recent messages
  • upload to PyPi


  • v0.2.0 - 2012-11-01
    • 'pb' subcommand to print the sorted phonebook
    • Fix a bug caused by change in upstream API (credit remaining uses ',' now instead of '.')
    • Print the number of chars used when sending
    • Accept messages on stdin
    • Option to output only the amount when using 'check'
    • Added a quickstart for busy people
  • v0.1.0 - 2012-08-20
    • Initial release
    • 'check' and 'send' subcommands
    • Phone book