Shawk - Free SMS with Python using SMTP and IMAP

A python smtplib and imapclient wrapper to send and receive SMS messages through SMS gateways with a Gmail login. Perfect for Internet of Things projects that use a Raspberry Pi to text you!

Disclaimer

This project is a work in progress, and as such, the API may change drastically before version 1.0 is reached. This repo may be out-of-sync with the PyPi version, so if you're interested in using the bleeding-edge features added since last tag, clone the repo and import locally. Tags will reflect PyPi published versions.

Installation

Shawk is available on PyPi as such:

pip install shawk

Documentation

To see full documentation and a more detailed Getting Started page, see here.

Simple Usage Example

Sending Messages

Create a Client:

Simply import shawk and define a Client by providing a Gmail username and password.

import shawk
client = shawk.Client('username@gmail.com', 'password')

(Optionally) Add Contacts:

Use the add_contact() function to add a contact's number as string or integer, carrier, and (optionally) a name. You can even pass in a lists of multiple numbers, names, and carriers.

client.add_contact("5551234567", 'Carrier', 'Name')
client.add_contact("18008675309", 'Carrier')

Send SMS:

Shawk can send texts either by providing a Contact object, phone number, or name.

client.send("Message content to send", SomeContact) # or contact=SomeContact
client.send("Message content to send", name="Name")
client.send("Message content to send", number="5551234567")

Receiving Messages Automatically

Shawk clients can be configured to automatically refresh their inbox and report back with new messages. In this mode, Shawk will poll the IMAP server periodically and check for new messages.

To do this, create your client with the auto=True parameter, or see the docs for other methods.

client = Shawk.Client('username@gmail.com', 'password', auto=True)

You can also change how frequently the server is queried:

client.set_refresh_interval(30) # Period time in seconds

Each time Shawk encounters a new message, it will pass its Message object to the handler function. You can define the behavior here with client.set_handler(some_function) where some_function accepts a Message object.

For example:

@client.text_handler()
def handler(client, msg):
    print("Hey, we're popular! {} texted us!".format(msg.sender))
    if isinstance(msg.sender, str):                      # if msg.sender is a string
        client.send("Hello, world!", address=msg.sender) # then msg.sender is an address
    else:
        client.send("Hello, world!", msg.sender)         # then msg.sender is a Contact