TutaBridge logo # TutaBridge **Use [Tuta](https://tuta.com) encrypted email in Thunderbird, Apple Mail, or any standard mail client.** A local IMAP/SMTP bridge that talks to Tuta's API and handles the end-to-end encryption transparently — so your favourite desktop client just works.
[![CI](https://github.com/spartanz51/tutabridge/actions/workflows/ci.yml/badge.svg)](https://github.com/spartanz51/tutabridge/actions/workflows/ci.yml) [![Latest release](https://img.shields.io/github/v/release/spartanz51/tutabridge?include_prereleases&sort=semver)](https://github.com/spartanz51/tutabridge/releases) [![License: GPL-3.0](https://img.shields.io/badge/license-GPL--3.0-blue.svg)](LICENSE) [![Platforms](https://img.shields.io/badge/platforms-macOS%20%7C%20Windows%20%7C%20Linux-lightgrey)](#-install) [![Built with Rust + Tauri](https://img.shields.io/badge/built%20with-Rust%20%2B%20Tauri-dea584?logo=rust)](#-build-from-source) [**Install**](#-install) · [**Getting started**](#-getting-started) · [**Features**](#-features) · [**Backup**](#-backup) · [**Architecture**](#-architecture)
> ⚠️ **Unofficial & unsigned.** TutaBridge is an independent project — not > affiliated with, endorsed by, or supported by Tuta. It logs into your account > and decrypts your mail locally, outside Tuta's official apps; use it at your > own risk. The released binaries are **not code-signed**, so macOS and Windows > warn on first launch — see [Install](#-install) for how to get past that. --- ## ✨ Features | | | |---|---| | 📥 **IMAP + SMTP** | Local TLS servers on `127.0.0.1` — any standard mail client connects. | | ⚡ **Realtime sync** | Tuta's WebSocket event bus pushes new mail, reads, moves and deletes; a heartbeat + idle-timeout reconnect dead sockets automatically. | | 🗂️ **Whole mailbox** | Every folder and message is listed — not just a recent slice. | | 🔍 **Honest search** | Subject / sender / date search the entire mailbox; full-text **body** search via an encrypted on-disk index. | | 📎 **Attachments** | Both ways — incoming served as `multipart/mixed`, outgoing uploaded to Tuta on send. | | 📝 **Folders & flags** | Drafts, custom / nested folders, move, trash, read/unread. | | 🔐 **Encrypted cache** | Metadata in SQLCipher, bodies as individually-encrypted `.eml.enc` files — usable instantly on relaunch, only the delta is fetched. | | 💾 **Complete backup** | Export *every* message to portable `.eml` files. | | 🔑 **2FA (TOTP)** | Two-factor login supported. | --- ## 📦 Install Download the latest build from the [**Releases**](https://github.com/spartanz51/tutabridge/releases) page. Every platform ships two flavours: - 🖥️ a **desktop app** — a normal double-click GUI, recommended for most people; - ⌨️ a **CLI binary** — a single executable you run from a terminal, for headless / server use. | Platform | Desktop app | CLI binary | |----------|-------------|------------| | **macOS** (Apple Silicon) | `TutaBridge_*_universal.dmg` | `tutabridge-macos-arm64` | | **Windows** (x64) | `TutaBridge_*_x64-setup.exe` *(or `.msi`)* | `tutabridge-windows-x86_64.exe` | | **Linux** (x64) | `*.AppImage` / `*.deb` / `*.rpm` | `tutabridge-linux-x86_64` | Because the binaries aren't signed, each OS needs a **one-time nudge** to run them:
🍎 macOS Open the `.dmg` and drag TutaBridge to **Applications**. On first launch macOS says the app *"cannot be opened because the developer cannot be verified"* — **right-click the app → Open → Open**, which whitelists it permanently. (A plain double-click won't offer the override.)
🪟 Windows Run the `.exe` or `.msi`. SmartScreen shows *"Windows protected your PC"* — click **More info → Run anyway**.
🐧 Linux ```bash chmod +x TutaBridge_*_amd64.AppImage && ./TutaBridge_*_amd64.AppImage # or: sudo dpkg -i TutaBridge_*_amd64.deb # Debian / Ubuntu # or: sudo rpm -i TutaBridge-*.x86_64.rpm # Fedora / RHEL ```
⌨️ CLI binary (any OS) The CLI files have **no extension**, so double-clicking does nothing useful (your OS may even open them in a text editor). Run them from a terminal: ```bash chmod +x tutabridge-macos-arm64 # make it executable xattr -d com.apple.quarantine tutabridge-macos-arm64 # macOS only: clear Gatekeeper ./tutabridge-macos-arm64 # run ```
--- ## 🚀 Getting started **1.** **Launch** the app (or run the CLI). On first run it asks for your Tuta email, then your password and TOTP code if there's no saved session. The session is stored in your OS keychain, so later launches resume automatically. **2.** TutaBridge shows the **local connection details**. Note the **bridge password** — this is generated by TutaBridge for local IMAP/SMTP auth and is **not** your Tuta password. *(CLI: printed in the logs · GUI: shown on the main screen.)* **3.** **Add the account** in your mail client with these settings: | | Server | Port | Security | Auth | |---|--------|------|----------|------| | **IMAP** (incoming) | `127.0.0.1` | `1143` | SSL/TLS | Normal password | | **SMTP** (outgoing) | `127.0.0.1` | `1025` | SSL/TLS | Normal password | > **Username:** your Tuta email  ·  **Password:** the bridge password from step 2 >  ·  accept the **self-signed certificate** when prompted. Keep TutaBridge running while you use your mail client — it *is* the local server the client talks to.
Client-specific notes (Thunderbird, Apple Mail) - **Thunderbird** — add the account manually (don't let auto-config probe public servers). Set both servers to `127.0.0.1` with SSL/TLS + "Normal password", and accept the certificate exception on first connect. - **Apple Mail** — add an *"Other Mail Account"*, then in **Server Settings** turn **off** "Automatically manage connection settings" so you can pin host `127.0.0.1`, the ports above, and TLS.
> [!NOTE] > **Search** runs in your mail client. Subject / sender / date search covers the > whole mailbox; **body** (full-text) search covers messages whose body has been > **downloaded**. Enable *"keep every message body offline"* (or raise the > offline-bodies limit) for full-mailbox body search. --- ## 🧭 Architecture Syncer-driven, store-backed — the IMAP server never makes a network call to *read*: ``` Tuta API ←── Syncer (background) ──→ MailStore (in-memory) ←── IMAP server ──→ mail client ←── GUI (stats) ``` - The **syncer** pulls from the Tuta API and populates an in-memory `MailStore`, backed by the on-disk encrypted cache. - The **IMAP server** only ever *reads* from the store — never an API call for reads. - The only IMAP→network calls are mutations: mark read/unread (`STORE \Seen`) and trash (`EXPUNGE`). Sending goes SMTP → Tuta's `DraftService` + `SendDraftService`. The storage encryption key is derived from your Tuta session, so there's no extra password to manage; the cache is encrypted at rest. --- ## 💾 Backup Export **every** email to a folder of plain `.eml` files — one per message, in a tree mirroring your IMAP folders. It enumerates all mail from the server (not just what's currently synced), so nothing is silently left out. ``` / ├── INBOX/ │ ├── 20260528-144935_OtjDuDU--3-9.eml │ └── … ├── Sent/ ├── Trash/ └── Café/Projets/… ``` ```bash tutabridge backup ~/TutaBackup # CLI ``` In the **GUI**, use the **Backup** tab — pick a folder, watch per-folder progress. *(The bridge must be running; the backup reuses its signed-in session.)* - **Format** — `.eml` (RFC 2822). Opens natively in Thunderbird / Apple Mail / Outlook, survives Windows filesystems, and one corrupt file never sinks the archive. Filenames are date-prefixed so a listing sorts chronologically. - **Resumable / incremental** — re-running into the same folder skips messages already on disk, so an interrupted backup resumes and a periodic re-backup only fetches new mail. - **Speed** — cached messages export instantly; the rest are fetched with a small politeness delay, so a first full backup of a large mailbox can take minutes. - **Scope** — every folder, including Trash and Spam. --- ## 🔨 Build from source Requires the Rust toolchain and the `tuta-repo` submodule (`git clone --recursive`, or `git submodule update --init --recursive`): ```bash cargo build # CLI + core cargo build -p tutabridge-core # core library only cargo run # run the CLI from source ./dev.sh # GUI in dev mode (cargo tauri dev) ``` --- ## 📁 Files & locations Config and cache live under your platform's app-data directory — on macOS `~/Library/Application Support/tutabridge/`: ``` config.toml account + ports + bridge_password + sync_limit store.db SQLCipher metadata + full-text body index mails/.eml.enc per-mail encrypted bodies ``` `sync_limit` controls how many recent message **bodies** are kept offline; the full mailbox is always listed and metadata-searchable regardless. Set it to `0` (or tick *"keep every message body offline"* in the GUI) to download everything. --- ## 🧪 Testing ```bash cargo test --workspace # unit + integration tests python3 scripts/test_imap.py # integration test against a running bridge ``` The IMAP integration test connects to the local server and verifies TLS, auth, folder list, mail count, body fetch and search. It reads the bridge password from `config.toml` automatically. --- ## 🔌 SDK TutaBridge depends on a few additions to Tuta's Rust SDK, vendored as the `tuta-repo` submodule. Each change is kept as its own single-commit branch off upstream for easy review / upstreaming — see [`SDK_PRS.md`](SDK_PRS.md) for status. --- ## 📄 License [GPL-3.0-or-later](LICENSE). TutaBridge links Tuta's Rust SDK (part of the GPLv3-licensed [tutanota](https://github.com/tutao/tutanota) project), so it is distributed under the same license.