tinystats

tinystats is a command-line tool for fetching message, URL, and subscriber data for the TinyLetter newsletters you own. Brought to you by Data Is Plural, a weekly newsletter of interesting/curious datasets.

Looking for more customized reports? Try tinyapi, the Python library that powers tinystats.

Warning

It's probably unwise to depend on tinystats for anything important. The library's functionality depends on TinyLetter's undocumented API. If that API changes, tinystats will likely break.

Installation

Run the following command from your computer's command line:

pip install tinystats

Usage

tinystats can run four types of reports:

messages: All messages you've sent; most recent first.
urls: All URLs you've linked to; most clicked first.
subscribers: All current subscribers to your newsletter; most recent first.
subcriber_count: Simply prints the current number of subscribers to your newsletter.

Commands take the following basic form:

tinystats [report-type] [your-newsletter-username]

Each command will print its results to the command line. So, to save a spreadsheet of every URL I've included in Data Is Plural as dip-urls.csv, I'd run this command:

tinystats urls data-is-plural > dip-urls.csv

Note: To fetch the data, you'll need to enter your password. For security reasons, tinystats does not store your password, and does not send it anywhere other than to TinyLetter's servers.

Details And Options

tinystats messages

usage: tinystats messages [-h] [--include-content] [-p PASSWORD] [-n N]
                          [--format {csv,json}] [--sep SEP]
                          [--fields FIELDS [FIELDS ...]]
                          username

All messages you've sent; most recent first.

positional arguments:
  username

optional arguments:
  -h, --help            show this help message and exit
  --include-content     Include message content.
  -p PASSWORD, --password PASSWORD
  -n N                  Return only first X results.
  --format {csv,json}
  --sep SEP             Separator for CSV fields. Defaults to a comma.
  --fields FIELDS [FIELDS ...]
                        Return only these fields

tinystats urls

usage: tinystats urls [-h] [-p PASSWORD] [-n N] [--format {csv,json}]
                      [--sep SEP] [--fields FIELDS [FIELDS ...]]
                      username

All URLs you've linked to; most clicked first.

positional arguments:
  username

optional arguments:
  -h, --help            show this help message and exit
  -p PASSWORD, --password PASSWORD
  -n N                  Return only first X results.
  --format {csv,json}
  --sep SEP             Separator for CSV fields. Defaults to a comma.
  --fields FIELDS [FIELDS ...]
                        Return only these fields

tinystats subscriber

usage: tinystats subscribers [-h] [-p PASSWORD] [-n N] [--format {csv,json}]
                             [--sep SEP] [--fields FIELDS [FIELDS ...]]
                             username

All current subscribers to your newsletter; most recent first.

positional arguments:
  username

optional arguments:
  -h, --help            show this help message and exit
  -p PASSWORD, --password PASSWORD
  -n N                  Return only first X results.
  --format {csv,json}
  --sep SEP             Separator for CSV fields. Defaults to a comma.
  --fields FIELDS [FIELDS ...]
                        Return only these fields

tinystats subscriber_count

usage: tinystats subscriber_count [-h] [-p PASSWORD] username

Current number of subscribers to your newsletter.

positional arguments:
  username

optional arguments:
  -h, --help            show this help message and exit
  -p PASSWORD, --password PASSWORD

Recipes

Overall "open rate"

export TINYSTATS_USER="your-username"

tinystats messages $TINYSTATS_USER --fields send_count stats.unique_opens | awk -F "," '{
    sends+=$1; opens+=$2;
} END {
    printf "Aggregate open rate: %d/%d = %.1f%%\n", opens, sends, 100 * opens / sends
}'

Feedback / Improvements?

I'm all ears.

jsvine/tinystats