guangzhiyao/bichon
1
0
Fork 0
mirror of https://github.com/rustmailer/bichon.git synced 2026-02-08 17:14:13 +01:00
Code Issues Projects Releases Packages Wiki Activity
Page: Using Bichonctl For Email Import
Pages
Configuration Reference Custom Storage Configuration De‐duplication FAQ (Frequently Asked Questions) Home How to Select Folders to Sync Permissions and Multi‐User System Reset Admin Password (Offline Tool) Securing Credentials: Encrypting Passwords and OAuth Tokens Setting the Bichon Encryption Password Store External OAuth2 Token API Using Bichonctl For Email Import
4 Using Bichonctl For Email Import
rustmailer edited this page 2026-01-25 11:42:13 +08:00
Unescape Escape
Table of Contents
This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

Using bichonctl

This page explains how to import existing email data into Bichon using bichonctl, an interactive command-line tool introduced in Bichon v0.3.0.

The goal of bichonctl is to make one‑time or temporary email imports safe, efficient, and easy, without complicating the core Bichon service.

1. Prerequisite: Create a NoSync Account

Before using bichonctl, you must create a NoSync account in the Bichon Web UI.

What is a NoSync account?

  • A NoSync account is a static mail account.
  • It does not connect to an IMAP server.
  • It only supports importing email data.
  • It requires no IMAP credentials, no connection tests, and no sync configuration.

Compared to IMAP accounts, NoSync accounts are simpler and safer for bulk or historical imports.

How to create one

  1. Open the Web UI
  2. Go to Accounts
  3. On the right side of the button, choose Add NoSync
  4. Fill in the basic account information and save

Important limitations

  • Email import is only allowed into NoSync accounts
  • Importing emails into IMAP accounts is intentionally not supported

This restriction avoids conflicts between imported data and live IMAP synchronization.

2. Why bichonctl Exists

Email import was intentionally not built into the main Bichon service:

  • Email archives (EML, MBOX) can be very large
  • Uploading them through the server would require moving large files over the network
  • Import tasks are usually temporary and one‑time

By separating this functionality:

  • The Bichon service remains simpler and more stable
  • Large files stay on the local machine
  • Imports can be optimized and batched efficiently

bichonctl focuses exclusively on local file parsing + API‑based ingestion.

3. Installing bichonctl

bichonctl is distributed as a precompiled binary.

Supported platforms

  • Windows
  • macOS
  • Linux

Installation steps

  1. Go to the GitHub Releases page
  2. Download the archive for your platform
  3. Extract the archive
  4. Locate the bichonctl executable

No build or compilation is required.

4. Running bichonctl

bichonctl is a command‑line application.

Windows

  • Use Command Prompt (cmd) or PowerShell
  • Place bichonctl.exe in a folder
  • Open a terminal in that folder

macOS / Linux

  • Use a terminal
  • Ensure the file is executable

Running on macOS

Note that the binary is not notarized, so if you download the release via browser, you won't be able to open it. Alternatively, you can remove the quarantine flag with:

xattr -d com.apple.quarantine /path/to/bichonctl

Running in Docker

docker run -it --rm -v $(pwd):/mnt rustmailer/bichon bichonctl

-v $(pwd):/mnt mounts your current folder into the container.

If your folder contains:

file.mbox

Enter this path when prompted:

/mnt/file.mbox

⚠️ Use the container path (/mnt/...), not your local system path.

5. Configuration File

bichonctl requires a small configuration file to know where your Bichon service is and who you are.

Default behavior

  • By default, bichonctl looks for a file named config.toml
  • It must be located in the current working directory
  • A different path can be specified via a command‑line argument

Required configuration fields

The configuration file contains two values:

  1. Bichon service base URL
  2. API token

API token and permissions

  • Bichon introduced multi‑user and permission management in v0.2.0
  • Each user can create their own API tokens
  • Importing emails requires data import permissions

Please refer to the official documentation for token creation and permission assignment:

https://github.com/rustmailer/bichon/wiki/Permissions-and-Multi%E2%80%90User-System

With this configuration, bichonctl can:

  • Authenticate the user
  • Discover which NoSync accounts the user is allowed to import into

6. Interactive Workflow

bichonctl is fully interactive.

After launching:

  1. The tool reads the configuration file
  2. Authenticates using the API token
  3. Displays a list of authorized NoSync accounts
  4. Prompts the user to select a target account
  5. Prompts the user to select an import mode

7. Import Modes

bichonctl supports various email archival formats to accommodate different migration scenarios.

7.1 Importing EML Files (Directory Mode)

This mode is designed for structured EML archives.

How it works

  • You provide a root directory on the local filesystem
  • Each folder maps to a mailbox folder in Bichon
  • EML files inside a folder are imported into the corresponding mailbox folder
  • Subdirectories are supported and preserved

Example

  • Root directory: E:/test
  • Folder: E:/test/Inbox
  • Result: Emails are imported into the Inbox folder of the selected NoSync account

bichonctl scans the entire directory tree and imports all detected EML files.

7.2 Importing a Single MBOX File

This mode is commonly used for Gmail Takeout or other single‑file exports.

Folder detection

  • bichonctl parses each email’s metadata
  • It examines label information stored in the message headers
  • System‑level status labels (such as read/unread state) are ignored
  • The remaining labels are analyzed to determine the most appropriate destination folder

The goal is to infer a meaningful mailbox folder automatically.

If automatic detection is not desired, you may also assign a fixed folder name for the entire MBOX file.

7.3 Importing Thunderbird Local Mail

This mode supports Thunderbird profiles and local mail directories.

How Thunderbird mail is handled

  • Thunderbird stores each mail folder as a separate MBOX file
  • Folder names correspond directly to mailbox names
  • Subfolders are represented by nested directories

bichonctl:

  • Detects the Thunderbird directory structure automatically
  • Preserves the folder hierarchy
  • Imports each mailbox into the matching folder in Bichon

7.4 Importing a Single PST File

This mode is designed for Outlook Personal Storage Table (.pst) files.

Automatic Folder Mapping

  • Hierarchy Preservation: bichonctl automatically scans the internal PST directory tree.
  • Seamless Sync: It recreates your original Outlook folders (e.g., Inbox/Archive/2025) directly within the target NoSync account in Bichon.

What is Imported?

To ensure efficiency and compatibility, bichonctl extracts only the essential components of each message:

  • Core Metadata: Standard headers including Subject, Date, Message-ID, In_Reply_To, References, From, To, CC, and BCC.
  • Content: Both Plain Text and HTML versions of the message body.
  • Attachments: All files and inline images embedded within the email are fully preserved.

8. Summary

Using bichonctl involves three high‑level steps:

  1. Create a NoSync account in the Web UI
  2. Configure bichonctl with a valid API token
  3. Run the interactive importer and choose an import mode

bichonctl is intentionally focused, conservative in scope, and designed to handle large local mail archives without burdening the Bichon service.

If you have large or historical email data to migrate, it is the recommended and supported approach.