2. Basic usage

Getting started

Before accessing the API, an APIClient object needs to be initialised, e.g.:
api = APIClient.APIClient()

In this documentation, function calls will always use the api.-prefix in reference to this API object.

Debug mode

The package contains a crude debug mode. This can be activated using the optional debug_output parameter of the APIClient object.:
api = APIClient(debug_output=True)

When active, the package will print all calls and responses to stdout, which is helpful when debugging calls or trying to dig through the response details.

Authentication

Authentication is done via the auth-function:
api.auth(username, password)

If the authentication was successful, the API will respond with an Auth ID for the session and the authentication level of the account:

Level: account  
Auth ID: foobar

Calling functions

After initialisation, API methods can be called, e.g. to authenticate:
api.auth(username, password)

Note: All function calls, except api.auth() and api.hello_world(), require prior authentication.

Naming scheme

Naming of the functions is aligned with the naming convention of the API itself (see https://api.mailbox.org).
The main difference is, that instead of periods, underscores are used (e.g. mail_add instead of mail.add).

Type hinting

Type hinting is used for (nearly) all functions. Some functions use **kwargs, e.g. mail_set. This is because of the large number of possible parameters. See also here:

Parameter input validation

Some calls include a large number of optional parameters, e.g. mail_set. In this case, the corresponding function includes a **kwargs parameter to accept a variable number of parameters.
For each parameter, the name and type are checked before sending it to the mailbox API. Errors will be raised if parameters (ValueError) or types (TypeError) are not matching.

Return values

The mailbox API (in most cases) returns a JSON with a result element like in this example:

Request:

{'method': 'domain.list', 'params': {'account': 'foo'}, 'jsonrpc': '2.0', 'id': '2'}

Return:

{'jsonrpc': '2.0', 'result': [{'domain': 'bar.com', 'count_mails': 4}], 'id': '2'}

or in case of a Boolean return:

{'jsonrpc': '2.0', 'result': True, 'id': '4'}

This package extracts the result of the returned JSON. For the examples above, the return from this package would therefore simply be:

[{'domain': 'bar.com', 'count_mails': 4}]

Or for the Boolean:

True

Example

Here's some example code on how to use the package:

from mailbox_org_api import APIClient

username = 'foo'
password = 'bar'

# Initializing
api = APIClient.APIClient()

# Testing with hello.world
api.hello_world()

# Creating a new API session
api.auth(username, password)

# Testing the session with hello.innerworld
api.hello_innerworld()

# Changing account settings
api.account_set('foo', {'payment_type':'invoice'})

# Creating an inbox
api.mail_add('foo@bar.com', 's3cr3tp4ssw0rd', 'standard', 'First Name', 'Last Name')

# Here are some examples for helper functions provided by this package

# Changing an inbox password
api.mail_set_password('foo@bar.com', 'an0th3rS3cr3t')

# Changing an inbox plan
api.mail_set_plan('foo@bar.com', 'premium')

# Deactivating an inbox
api.mail_set_state('foo@bar.com', False)

# Changing alias addresses
api.mail_set_aliases('foo@bar.com', ['alias1@bar.com', 'alias2@bar.com'])

# Changing forward addresses
api.mail_set_forwards('foo@bar.com', ['forward1@bar.com', 'forward2@bar.com'])

# Closing the session
api.deauth()