### Bichonctl Interactive Import Session Example

Source: https://context7.com/rustmailer/bichon/llms.txt

An example of an interactive session with the bichonctl command-line tool, demonstrating configuration loading, account selection, and email import.

```bash
$ ./bichonctl
> Config loaded: http://localhost:15630
> Select target account:
  1. Archive Import (NoSync)
> Import mode:
  1. EML directory
  2. MBOX file
  3. Thunderbird local mail
  4. PST file
> Enter path: /home/alice/exports/gmail-takeout/All Mail.mbox
> Importing 45,000 emails...  [=====>  ] 23% (10,350 / 45,000)
```

--------------------------------

### Get Startup Configuration Snapshot

Source: https://context7.com/rustmailer/bichon/llms.txt

Retrieves a snapshot of the system's startup configuration. This endpoint is Admin-only and requires an Authorization header.

```bash
curl -s http://localhost:15630/api/v1/system-configurations \
  -H "Authorization: $TOKEN"
```

--------------------------------

### Build Bichon WebUI

Source: https://github.com/rustmailer/bichon/blob/main/README.md

Install dependencies and build the WebUI using pnpm. This step is required before running the backend.

```bash
cd web
pnpm install
pnpm run build
```

--------------------------------

### Docker Compose Production Setup

Source: https://context7.com/rustmailer/bichon/llms.txt

Recommended production setup for Bichon using Docker Compose. Configures persistent storage, ports, and environment variables for a robust deployment.

```yaml
services:
  bichon:
    image: rustmailer/bichon:latest
    container_name: bichon
    ports:
      - "15630:15630"
    volumes:
      - ./bichon-data:/data
    user: "1000:1000"
    environment:
      BICHON_ROOT_DIR: /data
      BICHON_LOG_LEVEL: info
      BICHON_ENCRYPT_PASSWORD_FILE: /data/password.txt
      BICHON_CORS_ORIGINS: http://192.168.1.10:15630,https://mail.example.com
    restart: unless-stopped
```

--------------------------------

### Autoconfig Response Example

Source: https://context7.com/rustmailer/bichon/llms.txt

An example of the JSON response returned by the /api/v1/autoconfig/:email_address endpoint, detailing IMAP and SMTP server settings.

```json
# Response:
# {
#   "imap_host": "imap.gmail.com",
#   "imap_port": 993,
#   "imap_ssl": true,
#   "smtp_host": "smtp.gmail.com",
#   "smtp_port": 587
# }
```

--------------------------------

### Get startup configuration snapshot

Source: https://context7.com/rustmailer/bichon/llms.txt

Retrieves a snapshot of the system's startup configuration. This endpoint is restricted to administrative users.

```APIDOC
## GET /api/v1/system-configurations

### Description
Retrieves a snapshot of the system's current startup configuration. Access is limited to administrators.

### Method
GET

### Endpoint
/api/v1/system-configurations

### Request Example
```bash
curl -s http://localhost:15630/api/v1/system-configurations \
  -H "Authorization: $TOKEN"
```
```

--------------------------------

### Configuration Reference (Environment Variables)

Source: https://context7.com/rustmailer/bichon/llms.txt

Example of configuring Bichon using environment variables. Covers storage paths, logging, security, and performance settings.

```bash
# Full example using environment variables
export BICHON_ROOT_DIR=/opt/bichon-data
export BICHON_INDEX_DIR=/fast-ssd/envelope      # v0.3.2+: decouple metadata index
export BICHON_DATA_DIR=/large-hdd/eml            # v0.3.2+: decouple email data store
export BICHON_ENCRYPT_PASSWORD_FILE=/secrets/bichon.key  # v0.2.0+: password from file
export BICHON_HTTP_PORT=15630
export BICHON_BIND_IP=0.0.0.0
export BICHON_LOG_LEVEL=info                     # trace | debug | info | warn | error
export BICHON_LOG_TO_FILE=false
export BICHON_JSON_LOGS=false
export BICHON_CORS_ORIGINS=http://myserver.local:15630,https://mail.example.com
export BICHON_SYNC_CONCURRENCY=4                 # defaults to CPU cores × 2
export BICHON_METADATA_CACHE_SIZE=134217728      # 128 MB
export BICHON_ENVELOPE_CACHE_SIZE=1073741824     # 1 GB
export BICHON_ENABLE_REST_HTTPS=false
export BICHON_HTTP_COMPRESSION_ENABLED=true
export BICHON_WEBUI_TOKEN_EXPIRATION_HOURS=168   # 7 days
bichon
```

--------------------------------

### Run Bichon WebUI in Development

Source: https://github.com/rustmailer/bichon/blob/main/README.md

Start the WebUI in development mode for active development. This command is useful for making UI changes.

```bash
pnpm run dev
```

--------------------------------

### Docker Quick Start Deployment

Source: https://context7.com/rustmailer/bichon/llms.txt

Run Bichon using Docker for a minimal single-volume deployment. Access the WebUI at http://localhost:15630 with default credentials admin / admin@bichon.

```bash
# Minimal single-volume deployment
docker run -d \
  --name bichon \
  -p 15630:15630 \
  -v $(pwd)/bichon-data:/data \
  --user 1000:1000 \
  -e BICHON_ROOT_DIR=/data \
  -e BICHON_LOG_LEVEL=info \
  -e BICHON_ENCRYPT_PASSWORD=my-strong-password \
  rustmailer/bichon:latest

# Access the WebUI at http://localhost:15630
# Default credentials: admin / admin@bichon
```

--------------------------------

### Clone Bichon Repository

Source: https://github.com/rustmailer/bichon/blob/main/README.md

Clone the Bichon repository and navigate into the project directory. Ensure you have Git installed.

```bash
git clone https://github.com/rustmailer/bichon.git
cd bichon
```

--------------------------------

### External OAuth2 Request Body Example

Source: https://github.com/rustmailer/bichon/wiki/Store-External-OAuth2-Token-API

This is a general example of the request body structure for the store external OAuth2 token endpoint.

```json
{
  "oauth2_id": 123,
  "access_token": "ACCESS_TOKEN",
  "refresh_token": "REFRESH_TOKEN"
}
```

--------------------------------

### List All Users

Source: https://context7.com/rustmailer/bichon/llms.txt

Retrieve a list of all users in the system using the GET /api/v1/list-users endpoint. Requires user:manage permission.

```bash
# List all users (requires user:manage)
curl -s http://localhost:15630/api/v1/list-users \
  -H "Authorization: $TOKEN"
```

--------------------------------

### List All Roles

Source: https://context7.com/rustmailer/bichon/llms.txt

Retrieve a list of all available roles (both built-in and custom) using the GET /api/v1/list-roles endpoint. Requires user:manage permission.

```bash
# List all roles
curl -s http://localhost:15630/api/v1/list-roles \
  -H "Authorization: $TOKEN"
```

--------------------------------

### Get System Notifications

Source: https://context7.com/rustmailer/bichon/llms.txt

Fetches system notifications, including available updates and license warnings. Requires an Authorization header.

```bash
curl -s http://localhost:15630/api/v1/notifications \
  -H "Authorization: $TOKEN"
```

--------------------------------

### Get and Delete Account

Source: https://context7.com/rustmailer/bichon/llms.txt

Retrieve details for a specific account by its ID or delete an account. Deleting an account removes all its associated data.

```bash
# Get a single account
curl -s http://localhost:15630/api/v1/account/1 \
  -H "Authorization: $TOKEN"
```

```bash
# Delete an account (WARNING: removes all data)
curl -s -X DELETE http://localhost:15630/api/v1/account/1 \
  -H "Authorization: $TOKEN"
```

--------------------------------

### Get Account Statistics

Source: https://context7.com/rustmailer/bichon/llms.txt

Retrieve storage and message count statistics for a specific account. This provides an overview of the account's data usage within Bichon.

```bash
# Get storage/count statistics for account 1
curl -s http://localhost:15630/api/v1/accounts/1/stats \
  -H "Authorization: $TOKEN"
```

--------------------------------

### Discover IMAP Settings for an Email Address

Source: https://context7.com/rustmailer/bichon/llms.txt

Automatically resolve IMAP server settings for a given email address using the GET /api/v1/autoconfig/:email_address endpoint. Requires account:create permission.

```bash
# Discover mail server settings for an email address
curl -s http://localhost:15630/api/v1/autoconfig/alice@gmail.com \
  -H "Authorization: $TOKEN"
```

--------------------------------

### Get Current Authenticated User Profile

Source: https://context7.com/rustmailer/bichon/llms.txt

Fetch the profile information for the currently authenticated user via the GET /api/v1/current-user endpoint.

```bash
# Get the currently authenticated user's profile
curl -s http://localhost:15630/api/v1/current-user \
  -H "Authorization: $TOKEN"
```

--------------------------------

### Run bichonctl (Interactive Mode)

Source: https://context7.com/rustmailer/bichon/llms.txt

Launches the bichonctl CLI tool in interactive mode, prompting the user for account selection and import mode.

```bash
# Run bichonctl (interactive — prompts for account and import mode)
./bichonctl
```

--------------------------------

### Binary Deployment (Windows)

Source: https://context7.com/rustmailer/bichon/llms.txt

Deploy Bichon by downloading the binary for Windows. Configure root directory, encryption password, and log level.

```powershell
# Windows
.\bichon.exe --bichon-root-dir E:\\bichon-data --bichon-encrypt-password "my-strong-password"
```

--------------------------------

### Get a single account

Source: https://context7.com/rustmailer/bichon/llms.txt

Retrieves details for a specific account.

```APIDOC
## GET /api/v1/account/:id — Get a single account

### Description
Retrieves details for a specific account.

### Method
GET

### Endpoint
http://localhost:15630/api/v1/account/{id}

### Parameters
#### Path Parameters
- **id** (integer) - Required - The ID of the account to retrieve.

#### Headers
- **Authorization** (string) - Required - Bearer token for authentication.
```

--------------------------------

### Run Bichon Binary on Windows

Source: https://github.com/rustmailer/bichon/blob/main/README.md

Extract the downloaded binary and run it, specifying the required --bichon-root-dir argument with an absolute path.

```bash
# Windows
.\bichon.exe --bichon-root-dir e:\bichon-data
```

--------------------------------

### Get Current User Profile

Source: https://context7.com/rustmailer/bichon/llms.txt

Fetches the profile information for the currently authenticated user.

```APIDOC
## GET /api/v1/current-user — Get Current User Profile

### Description
Retrieves the profile details of the user who is currently authenticated via the API token.

### Method
GET

### Endpoint
/api/v1/current-user

### Response
#### Success Response (200)
- **user_profile** (object) - An object containing the current user's profile information (e.g., username, ID, roles).
```

--------------------------------

### Get Thread Messages

Source: https://context7.com/rustmailer/bichon/llms.txt

Retrieves all messages within a specific email thread, with support for pagination.

```APIDOC
## GET /api/v1/get-thread-messages/:account_id

### Description
Get all messages in a thread (paginated).

### Method
GET

### Endpoint
/api/v1/get-thread-messages/:account_id

### Parameters
#### Path Parameters
- **account_id** (integer) - Required - The ID of the account.
#### Query Parameters
- **thread_id** (string) - Required - The ID of the thread.
- **page** (integer) - Optional - The page number for pagination.
- **page_size** (integer) - Optional - The number of items per page.
```

--------------------------------

### Get storage/count statistics for an account

Source: https://context7.com/rustmailer/bichon/llms.txt

Retrieves storage and message count statistics for a specific account.

```APIDOC
## GET /api/v1/accounts/:id/stats — Get storage/count statistics for an account

### Description
Retrieves storage and message count statistics for a specific account.

### Method
GET

### Endpoint
http://localhost:15630/api/v1/accounts/{id}/stats

### Parameters
#### Path Parameters
- **id** (integer) - Required - The ID of the account to get statistics for.

#### Headers
- **Authorization** (string) - Required - Bearer token for authentication.
```

--------------------------------

### Get system notifications

Source: https://context7.com/rustmailer/bichon/llms.txt

Retrieves system notifications, which may include available updates or license warnings.

```APIDOC
## GET /api/v1/notifications

### Description
Retrieves system notifications, such as available software updates or license-related warnings.

### Method
GET

### Endpoint
/api/v1/notifications

### Request Example
```bash
curl -s http://localhost:15630/api/v1/notifications \
  -H "Authorization: $TOKEN"
```
```

--------------------------------

### Build from Source (Backend)

Source: https://context7.com/rustmailer/bichon/llms.txt

Build Bichon from source after cloning the repository and building the frontend. Requires setting an encryption password for development.

```bash
git clone https://github.com/rustmailer/bichon.git
cd bichon

# 1. Build the frontend
cd web && pnpm install && pnpm run build && cd ..

# 2. Run backend (requires WebUI build output)
export BICHON_ENCRYPT_PASSWORD=dummy-password-for-dev
cargo run -- --bichon-root-dir /tmp/bichon-data
```

--------------------------------

### Get Aggregated Metrics

Source: https://context7.com/rustmailer/bichon/llms.txt

Retrieves aggregated statistics across all authorized accounts. Requires an Authorization header.

```bash
curl -s http://localhost:15630/api/v1/dashboard-stats \
  -H "Authorization: $TOKEN"
```

--------------------------------

### Run Bichon Binary on Linux/macOS

Source: https://github.com/rustmailer/bichon/blob/main/README.md

Extract the downloaded binary and run it, specifying the required --bichon-root-dir argument with an absolute path.

```bash
# Linux/macOS
./bichon --bichon-root-dir /tmp/bichon-data
```

--------------------------------

### Binary Deployment (Linux/macOS)

Source: https://context7.com/rustmailer/bichon/llms.txt

Deploy Bichon by downloading the binary for Linux or macOS. Configure root directory, encryption password, and log level.

```bash
# Download from https://github.com/rustmailer/bichon/releases
# Linux/macOS
./bichon \
  --bichon-root-dir /opt/bichon-data \
  --bichon-encrypt-password "my-strong-password" \
  --bichon-log-level info
```

--------------------------------

### Configure Custom Storage Paths via CLI

Source: https://github.com/rustmailer/bichon/wiki/Custom-Storage-Configuration

Use command-line arguments to specify custom directories for Bichon's root, index, and data storage. This is useful when relocating these components to different drives.

```bash
cargo run --bin bichon -- \
  --bichon-root-dir "E:\bichon-data" \
  --bichon-index-dir "E:\envelope" \
  --bichon-data-dir "E:\eml"
```

--------------------------------

### Run Bichon Backend

Source: https://github.com/rustmailer/bichon/blob/main/README.md

Execute the Bichon backend service. Set the BICHON_ENCRYPT_PASSWORD environment variable for testing and specify the data directory using --bichon-root-dir.

```bash
export BICHON_ENCRYPT_PASSWORD=dummy-password-for-testing
cargo run -- --bichon-root-dir e:\bichon-data
```

--------------------------------

### Create an Email Account

Source: https://context7.com/rustmailer/bichon/llms.txt

Adds a new IMAP or NoSync account. Requires `account:create` permission.

```APIDOC
## POST /api/v1/account — Create an Email Account

### Description
Adds a new IMAP or NoSync account. Requires `account:create` permission.

### Method
POST

### Endpoint
http://localhost:15630/api/v1/account

### Parameters
#### Request Body
- **name** (string) - Required - The name of the account.
- **email** (string) - Required - The email address of the account.
- **account_type** (string) - Required - The type of account (e.g., "IMAP", "NoSync").
- **imap_host** (string) - Optional - The IMAP host for IMAP accounts.
- **imap_port** (integer) - Optional - The IMAP port for IMAP accounts.
- **imap_ssl** (boolean) - Optional - Whether to use SSL for IMAP connections.
- **username** (string) - Optional - The username for IMAP accounts.
- **password** (string) - Optional - The password for IMAP accounts.
- **sync_since_days** (integer) - Optional - The number of days to sync emails from for IMAP accounts.

### Request Example
```json
{
  "name": "Work Gmail",
  "email": "alice@example.com",
  "account_type": "IMAP",
  "imap_host": "imap.gmail.com",
  "imap_port": 993,
  "imap_ssl": true,
  "username": "alice@example.com",
  "password": "app-specific-password",
  "sync_since_days": 365
}
```

### Response
#### Success Response (200)
- **id** (integer) - The unique identifier for the created account.
- **name** (string) - The name of the account.
- **email** (string) - The email address of the account.
- ... (other AccountModel fields)

#### Response Example
```json
{ "id": 1, "name": "Work Gmail", "email": "alice@example.com", ... }
```
```

--------------------------------

### Build Bichon Backend

Source: https://github.com/rustmailer/bichon/blob/main/README.md

Compile the Rust backend using Cargo. This command should be run from the project root directory.

```bash
cd ..
cargo build
```

--------------------------------

### Custom Storage Layout Configuration

Source: https://context7.com/rustmailer/bichon/llms.txt

Configure Bichon to use separate drives for metadata and data indexes. Requires stopping Bichon, moving directories, and restarting with explicit paths.

```bash
# 1. Stop Bichon
# 2. Move directories:  mv /data/envelope /fast-ssd/  &&  mv /data/eml /large-hdd/
# 3. Restart with explicit paths:
bichon \
  --bichon-root-dir /data \
  --bichon-index-dir /fast-ssd/envelope \
  --bichon-data-dir /large-hdd/eml
```

--------------------------------

### Create an OAuth2 Configuration

Source: https://context7.com/rustmailer/bichon/llms.txt

Set up a new OAuth2 provider configuration, such as for Gmail or Microsoft 365, using the POST /api/v1/oauth2 endpoint. This is an Admin-only operation.

```bash
# Step 1: Create an OAuth2 configuration (Admin only)
curl -s -X POST http://localhost:15630/api/v1/oauth2 \
  -H "Authorization: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Gmail OAuth2",
    "client_id": "YOUR_GOOGLE_CLIENT_ID.apps.googleusercontent.com",
    "client_secret": "YOUR_CLIENT_SECRET",
    "auth_url": "https://accounts.google.com/o/oauth2/v2/auth",
    "token_url": "https://oauth2.googleapis.com/token",
    "scopes": ["https://mail.google.com/"]
  }'
```

--------------------------------

### Run Bichon Admin Tool

Source: https://github.com/rustmailer/bichon/wiki/Reset-Admin-Password-(Offline-Tool)

Execute the `bichon-admin` tool from the extracted archive on the same machine where `meta.db` resides. The tool will prompt for necessary information.

```bash
./bichon-admin
```

--------------------------------

### Set Password Using Password File (Environment Variable)

Source: https://github.com/rustmailer/bichon/wiki/Setting-the-Bichon-Encryption-Password

Set the environment variable to point to the password file, then run Bichon. This method is recommended for production environments.

```bash
export BICHON_ENCRYPT_PASSWORD_FILE=/path/to/password.txt
bichon
```

--------------------------------

### Get Messages in a Thread

Source: https://context7.com/rustmailer/bichon/llms.txt

Fetches all messages belonging to a specific thread, with pagination support. Requires account ID, thread ID, and pagination parameters.

```bash
# Get all messages in a thread (paginated)
curl -s "http://localhost:15630/api/v1/get-thread-messages/1?thread_id=thread-xyz&page=1&page_size=50" \
  -H "Authorization: $TOKEN"
```

--------------------------------

### Run Bichon Docker with Custom Storage

Source: https://github.com/rustmailer/bichon/blob/main/README.md

This command demonstrates running the Bichon Docker container with custom storage layouts for index and data directories. It maps additional volumes for envelope and eml files, allowing for more granular control over storage.

```bash
docker run -d \
  --name bichon \
  -p 15630:15630 \
  -v $(pwd)/bichon-data:/data \
  -v $(pwd)/envelope:/envelope \
  -v $(pwd)/eml:/eml \
  --user 1000:1000 \
  -e BICHON_ROOT_DIR=/data \
  -e BICHON_INDEX_DIR=/envelope \
  -e BICHON_DATA_DIR=/eml \
  rustmailer/bichon:latest
```

--------------------------------

### Create NoSync Account

Source: https://context7.com/rustmailer/bichon/llms.txt

Create an account of type 'NoSync' for use with `bichonctl` imports only. This type does not establish an IMAP connection.

```bash
# Create a NoSync account (for bichonctl imports only — no IMAP connection)
curl -s -X POST http://localhost:15630/api/v1/account \
  -H "Authorization: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Archive Import",
    "email": "archive@example.com",
    "account_type": "NoSync"
  }'
```

--------------------------------

### Get aggregated metrics across all authorized accounts

Source: https://context7.com/rustmailer/bichon/llms.txt

Retrieves comprehensive statistics including total emails, data size, index size, top senders, and a daily email count histogram.

```APIDOC
## GET /api/v1/dashboard-stats

### Description
Retrieves aggregated metrics across all authorized accounts, including total emails sent, total data size, index size, top senders, and a daily histogram of email counts.

### Method
GET

### Endpoint
/api/v1/dashboard-stats

### Request Example
```bash
curl -s http://localhost:15630/api/v1/dashboard-stats \
  -H "Authorization: $TOKEN"
```

### Response
#### Success Response (200)
- **total_emails** (integer) - Total number of emails processed.
- **total_size_bytes** (integer) - Total size of emails in bytes.
- **index_size_bytes** (integer) - Size of the email index in bytes.
- **top_senders** (array) - List of top email senders and their counts.
  - **email** (string) - The sender's email address.
  - **count** (integer) - The number of emails sent by the sender.
- **daily_histogram** (array) - Daily email count statistics.
  - **date** (string) - The date in YYYY-MM-DD format.
  - **count** (integer) - The number of emails on that date.

#### Response Example
```json
{
  "total_emails": 460000,
  "total_size_bytes": 145000000000,
  "index_size_bytes": 1300000000,
  "top_senders": [{ "email": "news@example.com", "count": 12000 }],
  "daily_histogram": [{ "date": "2024-12-01", "count": 320 }]
}
```
```

--------------------------------

### bichonctl Configuration

Source: https://context7.com/rustmailer/bichon/llms.txt

Configuration file for the bichonctl CLI tool. Specifies the base URL and API token for connecting to the Bichon server.

```toml
# Place in the current working directory before running bichonctl
base_url = "http://localhost:15630"
api_token = "WuqNC0g8yNle7CVnxcvjUwjN"
```

--------------------------------

### Create a User

Source: https://context7.com/rustmailer/bichon/llms.txt

Creates a new user with specified username, password, and global roles. Requires user:manage permission.

```APIDOC
## POST /api/v1/users — Create a User

### Description
Creates a new user with specified username, password, and global roles. Requires `user:manage` permission.

### Method
POST

### Endpoint
/api/v1/users

### Parameters
#### Request Body
- **username** (string) - Required - The username for the new user.
- **password** (string) - Required - The password for the new user.
- **global_roles** (array of integers) - Required - A list of role IDs to assign to the user. (e.g., 1=Admin, 2=Manager, 3=Member)

### Request Example
```json
{
  "username": "bob",
  "password": "securePass123!",
  "global_roles": [3]
}
```

### Response
#### Success Response (200)
- **user_id** (integer) - The ID of the newly created user.
- **message** (string) - Confirmation message.
```

--------------------------------

### Run bichonctl in Docker

Source: https://github.com/rustmailer/bichon/wiki/Using-Bichonctl-For-Email-Import

Use this command to run bichonctl within a Docker container. Mount your current directory to `/mnt` inside the container and provide the path to your email file within the container's filesystem.

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

--------------------------------

### Set Encryption Password via Command-Line

Source: https://github.com/rustmailer/bichon/wiki/Securing-Credentials:-Encrypting-Passwords-and-OAuth-Tokens

Use this command to provide the encryption password directly when running Bichon. This method takes precedence over environment variables.

```bash
bichon --bichon-encrypt-password "your-strong-password"
```

--------------------------------

### List SOCKS5 Proxies

Source: https://context7.com/rustmailer/bichon/llms.txt

Lists all available SOCKS5 proxies. These are visible to all authenticated users and require an Authorization header.

```bash
curl -s http://localhost:15630/api/v1/list-proxy \
  -H "Authorization: $TOKEN"
```

--------------------------------

### Set Password Using Password File (Command-Line)

Source: https://github.com/rustmailer/bichon/wiki/Setting-the-Bichon-Encryption-Password

Use this command to set the encryption password by referencing a password file. Ensure the file contains only the password string.

```bash
bichon --bichon-encrypt-password-file /path/to/password.txt
```

--------------------------------

### Enable HTTP Compression

Source: https://github.com/rustmailer/bichon/wiki/Configuration-Reference

Set `bichon_http_compression_enabled` to `true` to enable HTTP compression for API responses. This can be configured via CLI or environment variable.

```bash
bichon --bichon-http-compression-enabled=true
```

```bash
export BICHON_HTTP_COMPRESSION_ENABLED=true
```

--------------------------------

### Restart Bichon Service with Docker

Source: https://github.com/rustmailer/bichon/wiki/Reset-Admin-Password-(Offline-Tool)

Restart the bichon service after successfully resetting the admin password. Log in with the new credentials.

```bash
docker start bichon
```

--------------------------------

### Set Encryption Password via File

Source: https://context7.com/rustmailer/bichon/llms.txt

Sets the encryption password using a file, which is the recommended and most secure method for production. Ensure the file has restricted permissions (600).

```bash
# Method 1: Password file (recommended for production — most secure)
echo -n "my-very-strong-password" > /secrets/bichon.key
chmod 600 /secrets/bichon.key
bichon --bichon-encrypt-password-file /secrets/bichon.key --bichon-root-dir /data
```

--------------------------------

### Create OAuth2 Configuration

Source: https://context7.com/rustmailer/bichon/llms.txt

Sets up a new OAuth2 configuration for external authentication providers like Gmail or Microsoft 365. Requires Admin privileges.

```APIDOC
## POST /api/v1/oauth2 — Create OAuth2 Configuration

### Description
Configures a new OAuth2 integration for services like Gmail or Microsoft 365, enabling token-based authentication. This is an administrative operation.

### Method
POST

### Endpoint
/api/v1/oauth2

### Parameters
#### Request Body
- **name** (string) - Required - A descriptive name for the OAuth2 configuration (e.g., "Gmail OAuth2").
- **client_id** (string) - Required - The OAuth2 client ID obtained from the identity provider.
- **client_secret** (string) - Required - The OAuth2 client secret.
- **auth_url** (string) - Required - The authorization endpoint URL of the identity provider.
- **token_url** (string) - Required - The token endpoint URL of the identity provider.
- **scopes** (array of strings) - Required - The OAuth2 scopes required for the integration (e.g., ["https://mail.google.com/"]).

### Request Example
```json
{
  "name": "Gmail OAuth2",
  "client_id": "YOUR_GOOGLE_CLIENT_ID.apps.googleusercontent.com",
  "client_secret": "YOUR_CLIENT_SECRET",
  "auth_url": "https://accounts.google.com/o/oauth2/v2/auth",
  "token_url": "https://oauth2.googleapis.com/token",
  "scopes": ["https://mail.google.com/"]
}
```

### Response
#### Success Response (200)
- **oauth2_id** (integer) - The ID of the newly created OAuth2 configuration.
- **message** (string) - Confirmation message.
```

--------------------------------

### Login and Authenticate with Bichon API

Source: https://context7.com/rustmailer/bichon/llms.txt

Log in using default credentials to obtain a token. This token is then used in subsequent requests for authentication. Change default credentials in production.

```bash
curl -s -X POST http://localhost:15630/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "admin@bichon"}'
```

```bash
# Use in subsequent requests
curl -s http://localhost:15630/api/v1/current-user \
  -H "Authorization: $TOKEN"
```

--------------------------------

### Set Bichon Encryption Password

Source: https://github.com/rustmailer/bichon/blob/main/README.md

Refer to the provided wiki link for detailed instructions on setting the Bichon encryption password using command-line options, environment variables, or password files.

```bash
--bichon-cors-origins="https://mydomain"
```

--------------------------------

### List API Tokens

Source: https://context7.com/rustmailer/bichon/llms.txt

Lists all API tokens. Requires `token:manage` permission.

```APIDOC
## GET /api/v1/access-token-list — List API Tokens

### Description
Lists all API tokens. Requires `token:manage` permission.

### Method
GET

### Endpoint
http://localhost:15630/api/v1/access-token-list

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token for authentication.
```

--------------------------------

### Extract Bichon Release Archive

Source: https://github.com/rustmailer/bichon/wiki/Reset-Admin-Password-(Offline-Tool)

Extract the Bichon release archive on the host machine to access the `bichon-admin` tool. Ensure the version and architecture match your system.

```bash
tar -xzf bichon-<version>-linux-amd64.tar.gz
```

--------------------------------

### Docker with Encryption Password File

Source: https://context7.com/rustmailer/bichon/llms.txt

Runs the Bichon Docker container with the encryption password specified via a mounted password file. The password file should be mounted read-only.

```bash
# Docker with password file mounted
docker run -d \
  -v /secrets/bichon.key:/secrets/bichon.key:ro \
  -v $(pwd)/data:/data \
  -e BICHON_ENCRYPT_PASSWORD_FILE=/secrets/bichon.key \
  -e BICHON_ROOT_DIR=/data \
  rustmailer/bichon:latest
```

--------------------------------

### Create IMAP Account

Source: https://context7.com/rustmailer/bichon/llms.txt

Add a new IMAP account for email synchronization. Requires 'account:create' permission. Provide IMAP server details, username, password, and sync settings.

```bash
# Create an IMAP account with password authentication
curl -s -X POST http://localhost:15630/api/v1/account \
  -H "Authorization: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Work Gmail",
    "email": "alice@example.com",
    "account_type": "IMAP",
    "imap_host": "imap.gmail.com",
    "imap_port": 993,
    "imap_ssl": true,
    "username": "alice@example.com",
    "password": "app-specific-password",
    "sync_since_days": 365
  }'
```

--------------------------------

### Batch Import EML Files

Source: https://context7.com/rustmailer/bichon/llms.txt

Imports base64-encoded EML files into a NoSync account. Requires `data:import:batch` permission. Use `bichonctl` for large archives.

```bash
# Import two EML files into account 5, folder "Archive/2023"
EML1=$(base64 -w0 /path/to/email1.eml)
EML2=$(base64 -w0 /path/to/email2.eml)

curl -s -X POST http://localhost:15630/api/v1/import \
  -H "Authorization: $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"account_id\": 5,
    \"mail_folder\": \"Archive/2023\",
    \"emls\": [\"$EML1\", \"$EML2\"]
  }"
```

--------------------------------

### List all SOCKS5 proxies

Source: https://context7.com/rustmailer/bichon/llms.txt

Retrieves a list of all configured SOCKS5 proxies. This information is visible to all authenticated users.

```APIDOC
## GET /api/v1/list-proxy

### Description
Lists all SOCKS5 proxies that have been configured. This endpoint is accessible to all authenticated users.

### Method
GET

### Endpoint
/api/v1/list-proxy

### Request Example
```bash
curl -s http://localhost:15630/api/v1/list-proxy \
  -H "Authorization: $TOKEN"
```
```

--------------------------------

### List Mailboxes from Cache or Server

Source: https://context7.com/rustmailer/bichon/llms.txt

Fetch a list of mailboxes (folders) for a given account. Can query from the local cache or force a live fetch from the IMAP server.

```bash
# List mailboxes from local cache
curl -s http://localhost:15630/api/v1/list-mailboxes/1 \
  -H "Authorization: $TOKEN"
```

```bash
# Force a live query from the IMAP server
curl -s "http://localhost:15630/api/v1/list-mailboxes/1?remote=true" \
  -H "Authorization: $TOKEN"
```

--------------------------------

### Login with default admin credentials

Source: https://context7.com/rustmailer/bichon/llms.txt

Logs in using default admin credentials. It is recommended to change these immediately in a production environment.

```APIDOC
## POST /login

### Description
Logs in using default admin credentials. It is recommended to change these immediately in a production environment.

### Method
POST

### Endpoint
http://localhost:15630/login

### Request Body
- **username** (string) - Required - The username for login.
- **password** (string) - Required - The password for login.

### Request Example
```json
{
  "username": "admin",
  "password": "admin@bichon"
}
```

### Response
#### Success Response (200)
- **token** (string) - The authentication token.
- **user_id** (integer) - The ID of the logged-in user.
- **username** (string) - The username of the logged-in user.

#### Response Example
```json
{
  "token": "eyJ...",
  "user_id": 1,
  "username": "admin"
}
```
```

--------------------------------

### Batch Import EML Files

Source: https://context7.com/rustmailer/bichon/llms.txt

Imports base64-encoded EML files into a NoSync account. Requires `data:import:batch` permission.

```APIDOC
## POST /api/v1/import

### Description
Imports base64-encoded EML files into a NoSync account. Requires `data:import:batch` permission. For large local archives, use `bichonctl` instead.

### Method
POST

### Endpoint
/api/v1/import

### Parameters
#### Request Body
- **account_id** (integer) - Required - The ID of the account to import into.
- **mail_folder** (string) - Required - The destination folder for the imported emails.
- **emls** (array of string) - Required - An array of base64-encoded EML file contents.

### Request Example
```json
{
  "account_id": 5,
  "mail_folder": "Archive/2023",
  "emls": ["EML1_BASE64_ENCODED", "EML2_BASE64_ENCODED"]
}
```

### Response
#### Success Response (200)
- **total** (integer) - The total number of EML files processed.
- **success** (integer) - The number of successfully imported EML files.
- **failed** (integer) - The number of failed imports.
- **errors** (array) - A list of errors encountered during import.
```

--------------------------------

### Specify User ID and Group ID with Docker

Source: https://github.com/rustmailer/bichon/blob/main/README.md

Use Docker's native --user option to specify UID and GID for container file permissions matching host-mounted directories.

```bash
docker run --user 1000:1000 ...
```

--------------------------------

### Download Raw EML File

Source: https://context7.com/rustmailer/bichon/llms.txt

Downloads the original .eml file for a specific message. Requires account and envelope IDs.

```bash
# Download the original .eml file for a message
curl -s -OJ http://localhost:15630/api/v1/download-message/1/abc123 \
  -H "Authorization: $TOKEN"
```

--------------------------------

### List All Tags

Source: https://context7.com/rustmailer/bichon/llms.txt

Retrieves a list of all available tags along with their document counts. Tags are hierarchical paths.

```bash
# Get all tags with their document counts
curl -s http://localhost:15630/api/v1/all-tags \
  -H "Authorization: $TOKEN"
```

--------------------------------

### Run Bichon Docker Container

Source: https://github.com/rustmailer/bichon/blob/main/README.md

This command pulls the latest Bichon Docker image, creates a data directory, and runs the container in detached mode. It maps port 15630, mounts a local directory for data persistence, and sets the log level to info.

```bash
docker pull rustmailer/bichon:latest

mkdir -p ./bichon-data

docker run -d \
  --name bichon \
  -p 15630:15630 \
  -v $(pwd)/bichon-data:/data \
  --user 1000:1000 \
  -e BICHON_LOG_LEVEL=info \
  -e BICHON_ROOT_DIR=/data \
  rustmailer/bichon:latest
```

--------------------------------

### Create a Custom Role

Source: https://context7.com/rustmailer/bichon/llms.txt

Define and create a new custom role with specific permissions using the POST /api/v1/roles endpoint. Requires user:manage permission.

```bash
# Create a custom role with specific permissions
curl -s -X POST http://localhost:15630/api/v1/roles \
  -H "Authorization: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support",
    "role_type": "Account",
    "permissions": ["data:read", "data:manage"]
  }'
```

--------------------------------

### Create an API Token

Source: https://context7.com/rustmailer/bichon/llms.txt

Creates a long-lived API token for programmatic access or `bichonctl`. Requires any authenticated user.

```APIDOC
## POST /api/v1/access-token — Create an API Token

### Description
Creates a long-lived API token for programmatic access or `bichonctl`. Requires any authenticated user.

### Method
POST

### Endpoint
http://localhost:15630/api/v1/access-token

### Parameters
#### Request Body
- **name** (string) - Required - The name of the token.
- **expiration_days** (integer) - Required - The number of days until the token expires.

### Request Example
```json
{
  "name": "bichonctl-import",
  "expiration_days": 365
}
```

### Response
#### Success Response (200)
- **token** (string) - The created API token (plain text).

#### Response Example
```
WuqNC0g8yNle7CVnxcvjUwjN
```
```

--------------------------------

### List All Users

Source: https://context7.com/rustmailer/bichon/llms.txt

Retrieves a list of all users in the system. Requires user:manage permission.

```APIDOC
## GET /api/v1/list-users — List All Users

### Description
Retrieves a list of all users configured in the system. This operation requires `user:manage` permission.

### Method
GET

### Endpoint
/api/v1/list-users

### Response
#### Success Response (200)
- **users** (array of objects) - A list of user objects, each containing user details.
```

--------------------------------

### Manage API Tokens

Source: https://context7.com/rustmailer/bichon/llms.txt

List all API tokens or revoke a specific token. Token management requires the 'token:manage' permission.

```bash
# List all API tokens (requires token:manage permission)
curl -s http://localhost:15630/api/v1/access-token-list \
  -H "Authorization: $TOKEN"
```

```bash
# Revoke a specific token
curl -s -X DELETE "http://localhost:15630/api/v1/access-token/WuqNC0g8yNle7CVnxcvjUwjN" \
  -H "Authorization: $TOKEN"
```

--------------------------------

### List All Accounts

Source: https://context7.com/rustmailer/bichon/llms.txt

Retrieve a list of all accounts. Admins see all accounts, while non-admins see only those they are authorized for. Supports pagination and sorting.

```bash
# List all accounts (admin sees all; non-admin sees only authorized ones)
curl -s "http://localhost:15630/api/v1/accounts?page=1&page_size=20&desc=true" \
  -H "Authorization: $TOKEN"
```

--------------------------------

### Bichon Docker Compose Configuration

Source: https://github.com/rustmailer/bichon/blob/main/README.md

A recommended docker-compose configuration for running Bichon. It defines the service, image, container name, port mapping, volume mounts for data persistence, user, and environment variables for root directory and log level.

```yaml
services:
  bichon:
    image: rustmailer/bichon:latest
    container_name: bichon
    ports:
      - "15630:15630"
    volumes:
      - ./bichon-data:/data
    user: "1000:1000"
    environment:
      BICHON_ROOT_DIR: /data
      BICHON_LOG_LEVEL: info
```

--------------------------------

### Configure CORS with Single Origin

Source: https://context7.com/rustmailer/bichon/llms.txt

Sets up CORS for a single origin, typically used when Bichon is behind a reverse proxy. This is configured via environment variables during Docker container startup.

```bash
docker run -d rustmailer/bichon:latest \
  -e BICHON_ROOT_DIR=/data \
  -e BICHON_CORS_ORIGINS=https://mail.example.com
```

--------------------------------

### Discover IMAP Settings

Source: https://context7.com/rustmailer/bichon/llms.txt

Automatically discovers IMAP server settings for a given email address using protocols like Mozilla Autoconfig. Requires `account:create` permission.

```APIDOC
## GET /api/v1/autoconfig/:email_address — Discover IMAP Settings

### Description
Automatically resolves IMAP and SMTP server settings for an email address by querying standard autoconfiguration services. This is useful for setting up new email accounts.

### Method
GET

### Endpoint
/api/v1/autoconfig/{email_address}

### Parameters
#### Path Parameters
- **email_address** (string) - Required - The email address for which to discover settings.

### Response
#### Success Response (200)
- **imap_host** (string) - The IMAP server hostname.
- **imap_port** (integer) - The IMAP server port.
- **imap_ssl** (boolean) - Indicates if SSL/TLS is required for IMAP.
- **smtp_host** (string) - The SMTP server hostname.
- **smtp_port** (integer) - The SMTP server port.

### Response Example
```json
{
  "imap_host": "imap.gmail.com",
  "imap_port": 993,
  "imap_ssl": true,
  "smtp_host": "smtp.gmail.com",
  "smtp_port": 587
}
```
```

--------------------------------

### List Mailboxes/Folders

Source: https://context7.com/rustmailer/bichon/llms.txt

Returns folders cached locally or fetched live from the IMAP server. Default synced folders are INBOX and Sent; others must be explicitly enabled.

```APIDOC
## GET /api/v1/list-mailboxes/:account_id — List Mailboxes/Folders

### Description
Returns folders cached locally or fetched live from the IMAP server. Default synced folders are INBOX and Sent; others must be explicitly enabled.

### Method
GET

### Endpoint
http://localhost:15630/api/v1/list-mailboxes/{account_id}

### Parameters
#### Path Parameters
- **account_id** (integer) - Required - The ID of the account whose mailboxes to list.

#### Query Parameters
- **remote** (boolean) - Optional - If true, forces a live query from the IMAP server.

#### Headers
- **Authorization** (string) - Required - Bearer token for authentication.

### Response
#### Success Response (200)
- **id** (integer) - The mailbox ID.
- **account_id** (integer) - The ID of the account the mailbox belongs to.
- **name** (string) - The name of the mailbox/folder.
- **message_count** (integer) - The number of messages in the mailbox.
- **synced** (boolean) - Indicates if the mailbox is synced.

#### Response Example
```json
[
  { "id": 1, "account_id": 1, "name": "INBOX", "message_count": 9820, "synced": true },
  { "id": 2, "account_id": 1, "name": "Sent",  "message_count": 3200, "synced": true },
  { "id": 3, "account_id": 1, "name": "Archive", "message_count": 5000, "synced": false }
]
```
```

--------------------------------

### Restart Bichon Service with Docker Compose

Source: https://github.com/rustmailer/bichon/wiki/Reset-Admin-Password-(Offline-Tool)

Restart the bichon service using Docker Compose after the password reset. Use the new admin password for login.

```bash
docker compose up -d
```

--------------------------------

### Set Encryption Password via Environment Variable

Source: https://github.com/rustmailer/bichon/wiki/Securing-Credentials:-Encrypting-Passwords-and-OAuth-Tokens

Export the encryption password as an environment variable before running Bichon. This is an alternative to the command-line argument.

```bash
export BICHON_ENCRYPT_PASSWORD="your-strong-password"
bichon
```

--------------------------------

### Create a Regular Member User

Source: https://context7.com/rustmailer/bichon/llms.txt

Use the POST /api/v1/users endpoint to create a new user with a specified username, password, and global roles. Requires user:manage permission.

```bash
# Create a regular member user
curl -s -X POST http://localhost:15630/api/v1/users \
  -H "Authorization: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "bob",
    "password": "securePass123!",
    "global_roles": [3]
  }'
# Role IDs: 1=Admin, 2=Manager, 3=Member (built-in, non-deletable)
```

--------------------------------

### Trigger and Cancel Sync

Source: https://context7.com/rustmailer/bichon/llms.txt

Manually initiate a download/sync for an IMAP account or cancel an ongoing sync process. Use with caution as it can consume resources.

```bash
# Trigger a manual sync for account 1 (IMAP accounts only)
curl -s -X POST http://localhost:15630/api/v1/accounts/1/start-download \
  -H "Authorization: $TOKEN"
```

```bash
# Cancel the running manual sync
curl -s -X POST http://localhost:15630/api/v1/accounts/1/cancel-download \
  -H "Authorization: $TOKEN"
```

--------------------------------

### List All Roles

Source: https://context7.com/rustmailer/bichon/llms.txt

Retrieves a list of all available roles, including built-in and custom roles.

```APIDOC
## GET /api/v1/list-roles — List All Roles

### Description
Fetches a comprehensive list of all roles defined in the system, encompassing both predefined and custom roles.

### Method
GET

### Endpoint
/api/v1/list-roles

### Response
#### Success Response (200)
- **roles** (array of objects) - A list of role objects, each detailing a role's ID, name, type, and permissions.
```

--------------------------------

### Create API Token

Source: https://context7.com/rustmailer/bichon/llms.txt

Generate a long-lived API token for programmatic access. Requires any authenticated user. Specify the token name and expiration in days.

```bash
# Create a token with a 365-day expiration
curl -s -X POST http://localhost:15630/api/v1/access-token \
  -H "Authorization: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "bichonctl-import",
    "expiration_days": 365
  }'
```