helpscout-api

A simple Python interface to Helpscout API.

Python 3.5+

For development: Docker

You can use pip to install helpscout_api

pip install git+https://github.com/bufferapp/helpscout-api

If you prefer, you can clone it and run the setup.py file. Use the following commands to install helpscout-api from Github:

git clone https://github.com/bufferapp/helpscout-api
cd helpscout-api
python setup.py install

To use helpscout-api, you need your Helpscout API key.

Log in to Helpscout, go to 'Your Profile' > 'API keys'

Click on 'Generate an API Key' or copy the value of an existing one.

If you set the following environment variable, that package will use that key to authenticate:

HELPSCOUT_API_KEY=key_value

from helpscout_api import HelpscoutClient

helpscout = HelpscoutClient()
#or you can pass an explicit api key
helpscout = HelpscoutClient(api_key='your-api-key')

Now you can start calling the Helpscout API :D

Find the docs here: http://developer.helpscout.net/help-desk-api/

The client is implemented in tortilla, so you should be able to convert the endpoint url to a Python call pretty easily

#https://api.helpscout.net/v1/mailboxes.json
envelope = helpscout.api.mailboxes.get()

The Helpscout API has different kinds of result envelopes.

Single item envelope calls will just return the item directly

helpscout = HelpscoutClient()

mailbox = helpscout.api.mailboxes(1234).get()
print(mailbox.name)

Collections envelope calls will return a CollectionEnvelope object. The items property is a pandas dataframe

helpscout = HelpscoutClient()
result = helpscout.api.mailboxes().get()

print(result.count)
print(result.page)
print(result.pages)

result.items.head() #pandas dataframe

Results are limited to 50 items per page. To get another page, use the page parameter

helpscout = HelpscoutClient()
result = helpscout.api.mailboxes().get(params={'page':2})

Report api calls are returned as is:

from helpscout_api import format_dt

start = format_dt(datetime(2017,1,1))
end = format_dt(datetime(2017,1,2))
params = {'start':start, 'end':end}
report = helpscout.api.reports.conversations().get(params=params)

print(report.busiestDay) #access report fields directly

The development environment uses Docker. To get it set up just run:

make build
make test #to run the unit tests
make dev #command line access to the bash env