☰

OsProject

OsProject
edit
id	pyThunderbird
state	active
owner	WolfgangFahl
title	pyThunderbird
url	https://github.com/WolfgangFahl/pyThunderbird
version	0.4.0
description	python based access to Thunderbird mail
date	2026-07-07
since	2020-10-24
until

tickets

Motivation

Thunderbird uses mailbox format and an sqlite database for keeping track of the mails. How can this setup be accessed with Python?

Installation

pip install pyThunderbird
# alternatively if your pip is not a python3 pip
pip3 install pyThunderbird 
# local install from source directory of pyThunderbird 
pip install .

upgrade

pip install pyThunderbird  -U
# alternatively if your pip is not a python3 pip
pip3 install pyThunderbird -U

Demo

http://pythunderbird-demo.bitplan.com/

Usage

tbmail -h
usage: tbmail [-h] [-a] [-d] [--debugLocalPath DEBUGLOCALPATH]
              [--debugPort DEBUGPORT] [--debugRemotePath DEBUGREMOTEPATH]
              [--debugServer DEBUGSERVER] [-f] [-q] [-v] [-V]
              [--apache APACHE] [-c] [-l] [-i INPUT] [-rol] [--host HOST]
              [--port PORT] [-s] [-u USER] [-m MAILID]
              [-ul USER_LIST [USER_LIST ...]] [-ci]
              [-cil CREATE_INDEX_LIST [CREATE_INDEX_LIST ...]]
              [-ml MAILID_LIKE]
python based access to Thunderbird mail
options:
  -h, --help            show this help message and exit
  -a, --about           show version info and open documentation
  -d, --debug           enable debug output
  --debugLocalPath DEBUGLOCALPATH
                        remote debug Server path mapping - localPath - path on
                        machine where python runs
  --debugPort DEBUGPORT
                        remote debug Port [default: 5678]
  --debugRemotePath DEBUGREMOTEPATH
                        remote debug Server path mapping - remotePath - path
                        on debug server
  --debugServer DEBUGSERVER
                        remote debug Server
  -f, --force           force overwrite or unsafe actions
  -q, --quiet           suppress all output
  -v, --verbose         increase output verbosity
  -V, --version         show program's version number and exit
  --apache APACHE       create an apache configuration file for the given
                        domain
  -c, --client          start client
  -l, --local           run with local file system access
  -i INPUT, --input INPUT
                        input file
  -rol, --render_on_load
                        render on load
  --host HOST           the host to serve / listen from (default: localhost)
  --port PORT           the port to serve from (default: 8482)
  -s, --serve           start webserver
  -u USER, --user USER  id of the user
  -m MAILID, --mailid MAILID
                        id of the mail to retrieve
  -ul USER_LIST [USER_LIST ...], --user-list USER_LIST [USER_LIST ...]
  -ci, --create-index   create an alternative index for the given users's
                        Thunderbird mailarchive
  -cil CREATE_INDEX_LIST [CREATE_INDEX_LIST ...], --create-index-list CREATE_INDEX_LIST [CREATE_INDEX_LIST ...]
                        create an alternative index for the given list of
                        relative mailbox paths
  -ml MAILID_LIKE, --mailid-like MAILID_LIKE
                        SQL LIKE-style wildcard search for matching mail IDs

API

Since 0.4.0 the webserver offers a machine-readable JSON API; interactive OpenAPI documentation is served at /docs. If SSO credentials are configured on the host the /api/* endpoints require HTTP basic auth, otherwise they are open (like the demo).

endpoint	purpose	example
`/api/status`	service health, version and sso flag	status
`/api/version`	name, version, update date	version
`/api/archives`	overview of the served mail archives with index health verdict (ok/stale/missing)	archives
`/api/search/{user}`	search the mail index with substring (SQL LIKE) semantics per field: `subject`, `from_addr`, `to_addr`, `message_id` — combinable (AND), `limit` parameter, 400 if no criterion given	search subject=test
`/api/mail/{user}/{mailid}`	single mail with content negotiation via the Accept header: `application/json` (default), `text/html`, `text/plain` / `application/x-wiki` for WikiSon markup	—
`/api/index/{user}/status`	index freshness for one user	—
`/api/index/{user}` (POST)	trigger a (re)index run	—

Configuration

$HOME/.thunderbird/thunderbird.yaml

The yaml file has two entries per user

db: the path of the gloda (global-messages-sqlite)
profile: the path to the Thunderbird profile

MacOS Example

In this example we try to make sure that the python library doesn't interfere with the running thunderbird.

joe:
  db: /Users/joe/Library/Thunderbird/Profiles/klm97bfn.default/gloda.sqlite
  profile: /Users/wf/Library/Thunderbird/Profiles/klm97bfn.default
kathy:
  db: /Users/kathy/Library/Thunderbird/Profiles/war97k3r.default/gloda.sqlite
  profile: /Users/kathy/Library/Thunderbird/Profiles/war97k3r.default

gloda script

If you put this in your local bin directory you can call it from the command line any time you'd like to get an updated gloda that is a copy of the global-messages-db.sqlite you need to adapt the Profile location

#!/bin/bash
# WF 2021-09-22
# copy the thunderbird gloda sqlite database
cd /Users/joe/Library/Thunderbird/Profiles/klm97bfn.default
cp -p  global-messages-db.sqlite gloda.sqlite

Linux example

in this example the server runs from an rsync'ed backup of the thunderbird files of the different users

user123:
  db: /hd/diskAlpha/backup/siteAlpha.com/user123/Library/Thunderbird/Profiles/randomID1.default/global-messages-db.sqlite
  profile: /hd/diskAlpha/backup/siteAlpha.com/user123/Library/Thunderbird/Profiles/randomID1.default
user456:
  db: /hd/diskBeta/backup/siteBeta.com/user456/Library/Thunderbird/Profiles/randomID2.default/global-messages-db.sqlite
  profile: /hd/diskBeta/backup/siteBeta.com/user456/Library/Thunderbird/Profiles/randomID2.default

Contents