Metadata-Version: 2.4
Name: bormail
Version: 0.4.0
Summary: Terminal-based email reader using mu and textual
Author: Bor Development Team
License: MIT License
        
        Copyright (c) 2026 Bor Development Team
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/slosar/bor
Project-URL: Documentation, https://github.com/slosar/bor#readme
Project-URL: Repository, https://github.com/slosar/bor
Project-URL: Issues, https://github.com/slosar/bor/issues
Keywords: email,terminal,tui,mu,maildir
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Communications :: Email :: Email Clients (MUA)
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: textual>=0.40.0
Requires-Dist: tomli>=2.0.0; python_version < "3.11"
Requires-Dist: pyperclip>=1.8.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Provides-Extra: html
Requires-Dist: html2text>=2020.1.16; extra == "html"
Provides-Extra: images
Requires-Dist: Pillow>=9.0.0; extra == "images"
Provides-Extra: keyring
Requires-Dist: keyring>=23.0.0; extra == "keyring"
Provides-Extra: all
Requires-Dist: html2text>=2020.1.16; extra == "all"
Requires-Dist: keyring>=23.0.0; extra == "all"
Requires-Dist: Pillow>=9.0.0; extra == "all"
Dynamic: license-file

# Bor - Terminal Email Reader

[![Tests](https://github.com/slosar/bor/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/slosar/bor/actions/workflows/tests.yml) [![PyPI](https://img.shields.io/pypi/v/bormail.svg)](https://pypi.org/project/bormail/)

Bor means pine in Slovenian. Bor is also an email reader inspired by [pine](https://en.wikipedia.org/wiki/Pine_%28email_client%29).

I used to use pine and later its derivatives (alpine, realpine) until it became unsustainable. I switched to mu4e over a decade ago, but while I liked many things, it was never quite perfect.

A few years ago I switched away from emacs to VSCode and with the advent of AI coding I finally bite the bullet and made my very own mail client that works exactly the way I want it. Think of bor as pine dragged (by its feet) into 2025.

Bor uses [mu](https://djcbsoftware.nl/code/mu/) for email access under the hoold and [Textual](https://textual.textualize.io/) for the user interface.

## Some screenshots

### Message index
![alt text](./documentation/screenshots/image1.png)
### Tabbed message reading
![alt text](./documentation/screenshots/image2.png)
### In-terminal preview using kitty terminal protocol
![alt text](./documentation/screenshots/image3.png)

## Features

- **Fast email searching** using mu's powerful query language
- **Threaded message view** with visual indentation
- **Message composition** with address autocompletion and Ctrl-C/V/X handling global clipboard even in terminal
- **Attachment handling** with preview (using kitty terminal graphics capabilities) 
- **Keyboard-driven interface** 
- **Tab-based workflow** 
- **Configurable** via TOML configuration file
- **HTML email support** via html2text rendering

## Requirements

- Python 3.10+
- [mu](https://djcbsoftware.nl/code/mu/) (maildir indexer)
- [Textual](https://textual.textualize.io/) library
- Optional: html2text for HTML email rendering
- Optional: kitty terminal for image preview


## Known issues

- no support for folders. You can mu search with maildir:/folder, but all archived messages go to the archived folder. This is how my work-flow works. Feel free to add and make pull request.
- Clicking with mouse on the link does not work. For emails with one or two links, 'O' shortcut is preferrable, but for complex long messages, clicking on the link would be better.

## Installation

### From PyPI

```bash
pip install bormail
```

### From source

```bash
# Clone the repository
git clone https://github.com/your-repo/bor.git
cd bor

# Install with pip
pip install -e .

# Or install dependencies manually
pip install textual tomli html2text
```

### Dependencies

```bash
# Install mu on Debian/Ubuntu
sudo apt install maildir-utils

# Install mu on Arch Linux
sudo pacman -S mu

# Install mu on macOS
brew install mu
```

## Release

1. Update the version in `pyproject.toml`.
2. Create a git tag like `v0.1.1` and publish a GitHub Release.
3. The Build workflow will upload the sdist and wheel to PyPI.
    - Configure PyPI Trusted Publishing for `slosar/bor` before the first release.

## Configuration

Copy the example configuration file and customize it:

```bash
cp bor.conf.example ~/.config/bor.conf
```

Edit `~/.config/bor.conf` to configure:
- SMTP server settings
- Maildir folder paths
- Display preferences
- Color scheme
- Synchronization command
- Email and text aliases

See the [configuration documentation](documentation/configuration.md) for details.

## Usage

Start Bor:

```bash
python -m bor.app
```

Or if installed:

```bash
bor
```

## Keyboard Shortcuts

### Global

| Key | Action |
|-----|--------|
| Alt+0 | Message Index tab |
| Alt+1-9 | Switch to tab |
| Ctrl+Q | Quit |

### Message Index

| Key | Action |
|-----|--------|
| ↑/↓ or N/P | Navigate messages |
| Enter | Open message |
| R | Reply |
| F | Forward |
| C | Compose new |
| S | Search (mu query) |
| I | Show Inbox |
| O | Show Archive |
| U | Show Drafts |
| M | Mark message |
| X | Archive message(s) |
| A | Apply flag |
| D | Delete message(s) |
| E | Edit draft |
| T | Toggle threading |
| Ctrl+T | Show thread |
| L | Sync |
| Z | Undo move |
| Ctrl+R | Refresh index |

### Message View

| Key | Action |
|-----|--------|
| Space/PgDn | Scroll down |
| < | Return to index (keep tab open) |
| Q | Close tab and return |
| N/P | Next/Previous message |
| R | Reply |
| F | Forward |
| C | Compose new |
| M | Mark/unmark message and advance |
| X | Archive |
| D | Delete |
| A | Apply flag |
| O | Open URL (if multiple, pick [1-9]) |
| Z | View attachments |
| Ctrl+R | Toggle full headers |

### Compose

| Key | Action |
|-----|--------|
| Tab | Autocomplete address/text |
| Ctrl+L L | Send message |
| Ctrl+L D | Save draft |
| Ctrl+L X | Cancel |
| Ctrl+I | Insert file |
| Ctrl+A | Attach file |

### Attachments

| Key | Action |
|-----|--------|
| 1-9 | Select attachment |
| Enter | Open with system viewer |
| S | Save attachment |
| Shift+S | Save all |
| Q or Esc | Close and return to message view |
| < | Return to index (keep tab open) |

**URL opener limitation**

The URL picker shows and opens the first 9 URLs. If a message has more than 9 URLs, it is easier to copy/paste the link or use terminal link clicking instead.

## Search Queries

Bor uses mu's query language. Examples:

```
# Search in inbox
maildir:/INBOX

# Unread messages
flag:unread

# From a specific sender
from:john@example.com

# Subject contains word
subject:meeting

# Date range
date:1w..now

# Combine queries
from:john subject:meeting flag:unread
```

## License

MIT. See [LICENSE](LICENSE).

See the [mu query documentation](https://djcbsoftware.nl/code/mu/mu4e/Queries.html) for more.

## Development

### Project Structure

```
bor/
├── __init__.py       # Package init
├── app.py            # Main Textual application
├── config.py         # Configuration handling
├── mu.py             # Mu interface
└── tabs/
    ├── __init__.py
    ├── base.py       # Base tab class
    ├── message_index.py
    ├── message.py
    ├── compose.py
    ├── attachments.py
    └── sync.py
```

### Running tests

```bash
pytest tests/
```

## License

MIT License - see LICENSE file for details.

## Credits

- [mu/mu4e](https://djcbsoftware.nl/code/mu/) - Email indexing and searching
- [Textual](https://textual.textualize.io/) - TUI framework
- Inspired by traditional email clients like pine, mutt, and mu4e
