pywebfaction¶

pywebfaction is a tool for interacting with the WebFaction API. It is a fairly thin wrapper around the XML-RPC client, adding a few convenience methods, and pulling out the parts of responses that you’re probably interested in.

pywebfaction is two things - an API and a command-line tool.

So far, it is only concerned with the parts of the API for handling emails, though pull requests to change that are welcome.

Installation¶

pywebfaction can be installed with pip:

pip install pywebfaction

Contents¶

The pywebfaction API¶

Basic Usage¶

The API is interacted with via the class WebFactionAPI, which takes a username and password, and connects to WebFaction for you.

from pywebfaction import WebFactionAPI

api = WebFactionAPI(username, password)
emails = api.list_emails()

Available Methods¶

list_emails¶

list_emails takes no arguments, and give you back a list of objects representing the email addresses set up in your WebFaction account, along with what they do (i.e. whether they go to a local mailbox, or are forwarded elsewhere).

Usage is:

from pywebfaction import WebFactionAPI

api = WebFactionAPI(username, password)
emails = api.list_emails()

for email in emails:
    print email.address
    print email.mailboxes
    print email.forwards_to
create_email¶

create_email takes an email address, and sets up a standard email address in your WebFaction account, including creation of a local mailbox for storing your email. It takes a single argument (the email address to create), and returns a response object containing the mailbox name and password (which you’ll need for setting up your email client), and the ID of the email address created.

Any errors encountered will raise a WebFactionFault exception, except for the case where the provided email address is empty, or contains no characters that are valid as part of the generated mailbox name (in this case, ValueError will be raised).

Usage is:

from pywebfaction import WebFactionAPI, WebFactionFault

try:
    api = WebFactionAPI(username, password)
    response = api.create_email('dominic@example.com')

    print response.mailbox
    print response.password
    print response.email_id
except WebFactionFault as e:
    print e.exception_type  # e.g. 'DataError'
    print e.message  # e.g. 'Mailbox with this Name already exists.'
create_email_forwarder¶

create_email_forwarder takes two arguments - an email address to forward emails from, and a list of email addresses to forward to, and sets up a corresponding entry in your WebFaction account. The returned value is the ID of the resulting email address in WebFaction.

Usage is:

from pywebfaction import WebFactionAPI

api = WebFactionAPI(username, password)
email_id = api.create_email_forwarder(
    'dominic@example.com',
    ['barry@example.org', 'lucy@example.net', ]
)

print email_id

Command-line Usage¶

Once pywebfaction is installed, a command-line tool is available called pywebfaction, running it will print the help message:

Usage:
  pywebfaction generate_config --username=<username> --password=<password>
  pywebfaction list_emails
  pywebfaction create_email <addr>
  pywebfaction create_forwarder <addr> <fwd1>
  pywebfaction (-h | --help)
  pywebfaction --version

generate_config¶

generate_config will create a file called pywebfaction.ini in your home directory, to save you having to pass in a username and password to every other command. Note that none of the other commands will work if you do not have a pywebfaction.ini file in your home directory.

list_emails¶

The command list_emails will print a table showing what emails are set up on your WebFaction account, along with what mailboxes they are saved to, and what addresses they forward mail to.

create_email¶

The command create_email will set you up an email address and a corresponding mailbox, and tell you what the name of the mailbox created was, and what password was set up for it. The information printed out should be all you need to follow WebFaction’s instructions for configuring email clients.

create_forwarder¶

The command create_forwarder will set up an email address which forwards to another email address (the forwarding address can be any email address, not necessarily one on WebFaction).