### Install dependencies and run Gulp

Source: https://github.com/the-djmaze/snappymail/blob/master/CONTRIBUTING.md

Install project dependencies and execute the Gulp build process.

```bash
yarn install
```

```bash
gulp
```

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

### Install OpenPGP.js for Node.js

Source: https://github.com/the-djmaze/snappymail/blob/master/vendors/openpgp-5/README.md

Install the library via npm for use in Node.js environments.

```bash
npm install --save openpgp
```

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

### Start Snappymail with SQLite

Source: https://github.com/the-djmaze/snappymail/blob/master/examples/docker/Docker.md

Use this command to start Snappymail with SQLite as the database. Ensure the docker-compose.simple.yml file is present.

```sh
docker-compose -f docker-compose.simple.yml up
```

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

### Install Gulp globally

Source: https://github.com/the-djmaze/snappymail/blob/master/CONTRIBUTING.md

Install the Gulp task runner globally using npm.

```bash
npm install gulp -g
```

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

### Install SnappyMail via SSH

Source: https://context7.com/the-djmaze/snappymail/llms.txt

Commands to download, extract, and set file permissions for a manual web server installation.

```bash
# Navigate to web directory and download latest release
cd /var/www/webmail/snappymail
wget https://snappymail.eu/repository/latest.tar.gz
tar -xzf latest.tar.gz

# Set correct permissions
find /var/www/webmail/snappymail -type d -exec chmod 755 {} \;
find /var/www/webmail/snappymail -type f -exec chmod 644 {} \;
chown -R www-data:www-data /var/www/webmail/snappymail

# Access admin panel at https://example.com/?admin
# Default credentials found in: data/_data_/_default_/admin_password.txt
```

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

### Install OpenPGP.js for Webpack

Source: https://github.com/the-djmaze/snappymail/blob/master/vendors/openpgp-5/README.md

Install the library as a development dependency for browser projects.

```bash
npm install --save-dev openpgp
```

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

### Start Snappymail with PostgreSQL

Source: https://github.com/the-djmaze/snappymail/blob/master/examples/docker/Docker.md

Launches Snappymail alongside a PostgreSQL database service. Uses the docker-compose.postgres.yml file.

```sh
docker-compose -f docker-compose.postgres.yml up
```

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

### Start Snappymail with MariaDB/MySQL

Source: https://github.com/the-djmaze/snappymail/blob/master/examples/docker/Docker.md

Initiates Snappymail and a MariaDB/MySQL database service. Requires the docker-compose.mysql.yml file.

```sh
docker-compose -f docker-compose.mysql.yml up
```

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

### Install build dependencies

Source: https://github.com/the-djmaze/snappymail/blob/master/vendors/knockout/README.md

Install the Grunt CLI globally and fetch project-specific dependencies.

```sh
npm install -g grunt-cli
npm install
```

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

### Install Predis with Composer

Source: https://github.com/the-djmaze/snappymail/blob/master/plugins/cache-redis/README.md

Use Composer to add Predis as a project dependency. This is the recommended method for managing library installations.

```shell
composer require predis/predis
```

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

### Initialize SnappyMail PHP API

Source: https://context7.com/the-djmaze/snappymail/llms.txt

Setup required to access SnappyMail internal classes and configuration programmatically.

```php
<?php
// Set environment variable before requiring
$_ENV['SNAPPYMAIL_INCLUDE_AS_API'] = true;
require_once '/path/to/snappymail_root/index.php';

// Or include a specific version directly
// require_once '/path/to/snappymail_root/snappymail/v/2.36.1/include.php';

// Get the Actions instance for interacting with the application
$actions = \RainLoop\Api::Actions();

// Get the application configuration
$config = \RainLoop\Api::Config();

// Get the logger instance
$logger = \RainLoop\Api::Logger();

// Get Content Security Policy handler
$csp = \RainLoop\Api::getCSP($scriptNonce);
```

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

### Start Snappymail with Traefik

Source: https://github.com/the-djmaze/snappymail/blob/master/examples/docker/Docker.md

Launches Snappymail and Traefik, with Traefik acting as a TLS reverse proxy. Requires the docker-compose.traefik.yml file and configured environment variables.

```sh
docker-compose -f docker-compose.traefik.yml up
```

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

### Install SnappyMail via SSH

Source: https://github.com/the-djmaze/snappymail/wiki/Installation-instructions

Use these commands to download, extract, and set permissions for SnappyMail installation via SSH.

```sh
# Go to the directory where you want to install into
cd /var/www/webmail/snappymail
# Download and extract
wget https://snappymail.eu/repository/latest.tar.gz
tar -xzf latest.tar.gz
# Set permissions
find /var/www/webmail/snappymail -type d -exec chmod 755 {} \;
find /var/www/webmail/snappymail -type f -exec chmod 644 {} \;
chown -R www-data:www-data /var/www/webmail/snappymail
```

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

### Basic Plugin Structure

Source: https://context7.com/the-djmaze/snappymail/llms.txt

Extend AbstractPlugin to create a custom plugin. Implement Init() for setup and configMapping() for admin options. Use addHook() to register event listeners and addJs()/addCss() for frontend assets.

```php
<?php
// plugins/my-plugin/index.php

class MyPlugin extends \RainLoop\Plugins\AbstractPlugin
{
    const
        NAME     = 'My Custom Plugin',
        AUTHOR   = 'Your Name',
        URL      = 'https://example.com/',
        VERSION  = '1.0',
        RELEASE  = '2024-01-15',
        REQUIRED = '2.30.0',
        CATEGORY = 'General',
        LICENSE  = 'MIT',
        DESCRIPTION = 'A custom plugin that demonstrates the plugin API';

    /**
     * Initialize the plugin - register hooks, add JS/CSS
     */
    public function Init(): void
    {
        // Register hooks for various events
        $this->addHook('login.credentials.step-1', 'onLoginStep1');
        $this->addHook('login.credentials.step-2', 'onLoginStep2');
        $this->addHook('login.success', 'onLoginSuccess');
        $this->addHook('filter.send-message', 'onSendMessage');

        // Add custom JavaScript and CSS
        $this->addJs('js/my-plugin.js');
        $this->addCss('css/my-plugin.css');

        // Add custom JSON API endpoint
        $this->addJsonHook('PluginCustomAction', 'doCustomAction');

        // Add custom template
        $this->addTemplate('templates/MyTemplate.html');

        // Enable language files from langs/ folder
        $this->UseLangs(true);
    }

    /**
     * Plugin configuration options for admin panel
     */
    protected function configMapping(): array
    {
        return [
            \RainLoop\Plugins\Property::NewInstance('api_key')
                ->SetLabel('API Key')
                ->SetType(\RainLoop\Enumerations\PluginPropertyType::STRING)
                ->SetDescription('Enter your API key')
                ->SetDefaultValue(''),

            \RainLoop\Plugins\Property::NewInstance('enable_feature')
                ->SetLabel('Enable Feature')
                ->SetType(\RainLoop\Enumerations\PluginPropertyType::BOOL)
                ->SetDefaultValue(true),

            \RainLoop\Plugins\Property::NewInstance('log_level')
                ->SetLabel('Log Level')
                ->SetType(\RainLoop\Enumerations\PluginPropertyType::SELECTION)
                ->SetDefaultValue(['debug', 'info', 'warning', 'error'])
        ];
    }

    /**
     * Modify email before domain resolution
     */
    public function onLoginStep1(string &$sEmail): void
    {
        // Normalize email addresses
        $sEmail = strtolower(trim($sEmail));
    }

    /**
     * Modify credentials after domain resolution
     */
    public function onLoginStep2(string &$sEmail, string &$sPassword): void
    {
        // Custom authentication logic
        $apiKey = $this->Config()->Get('plugin', 'api_key', '');

        if ($apiKey && $this->Config()->Get('plugin', 'enable_feature', true)) {
            // Perform external validation
            $this->Manager()->WriteLog("Login attempt for: {$sEmail}");
        }
    }

    /**
     * Handle successful login
     */
    public function onLoginSuccess(\RainLoop\Model\MainAccount $oAccount): void
    {
        // Log successful login or perform post-login actions
        $email = $oAccount->Email();
        $this->Manager()->WriteLog("Successful login: {$email}");
    }

    /**
     * Modify outgoing messages
     */
    public function onSendMessage(\MailSo\Mime\Message $oMessage): void
    {
        // Add custom header to all outgoing messages
        $oMessage->SetCustomHeader('X-My-Plugin', 'v1.0');
    }

    /**
     * Custom JSON API endpoint handler
     * Called via: /?/Json/&q[]=/0/PluginCustomAction
     */
    public function doCustomAction(): array
    {
        $param = $this->jsonParam('myParam', 'default');

        // Perform action and return response
        return $this->jsonResponse(__FUNCTION__, [
            'success' => true,
            'data' => [
                'param' => $param,
                'timestamp' => time()
            ]
        ]);
    }
}

```

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

### Install TypeScript Dependencies

Source: https://github.com/the-djmaze/snappymail/blob/master/vendors/openpgp-5/README.md

Required command to install web-stream-tools for TypeScript projects using OpenPGP.js v5.

```sh
npm install --save-dev @openpgp/web-stream-tools@0.0.11-patch-0
```

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

### Connect to Redis with URI String

Source: https://github.com/the-djmaze/snappymail/blob/master/plugins/cache-redis/README.md

Connects to Redis using a URI string format, which is useful when parameters are read from non-structured sources. This example shows the equivalent of the named array parameters.

```php
$client = new Predis\Client('tcp://10.0.0.1:6379');
```

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

### Get Snappymail Admin Password (PostgreSQL)

Source: https://github.com/the-djmaze/snappymail/blob/master/examples/docker/Docker.md

Retrieves the admin panel password for the PostgreSQL setup. This command targets the Snappymail container.

```sh
docker exec -it $( docker-compose -f docker-compose.postgres.yml ps -q snappymail ) cat /var/lib/snappymail/_data_/_default_/admin_password.txt
```

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

### Get Snappymail Admin Password (MariaDB/MySQL)

Source: https://github.com/the-djmaze/snappymail/blob/master/examples/docker/Docker.md

Fetches the admin panel password for the MariaDB/MySQL setup. This command targets the Snappymail container.

```sh
docker exec -it $( docker-compose -f docker-compose.mysql.yml ps -q snappymail ) cat /var/lib/snappymail/_data_/_default_/admin_password.txt
```

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

### Navigate to project directory

Source: https://github.com/the-djmaze/snappymail/blob/master/CONTRIBUTING.md

Change the current working directory to the cloned project folder.

```bash
cd snappymail
```

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

### Build the library

Source: https://github.com/the-djmaze/snappymail/blob/master/vendors/knockout/README.md

Execute the build process to generate output files in the build/output/ directory.

```sh
grunt
```

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

### Initialize and Use SnappyMail API

Source: https://github.com/the-djmaze/snappymail/wiki/API

Configures the environment to include SnappyMail as an API and demonstrates access to core service components and user management methods.

```php
<?php

$_ENV['SNAPPYMAIL_INCLUDE_AS_API'] = true;
require_once '/path/to/snappymail_root/index.php';
// or with specific version
//require_once '/path/to/snappymail_root/snappymail/v/2.36.1/include.php';

// returns instance of \RainLoop\Actions
\RainLoop\Api::Actions();

// returns instance of \RainLoop\Config\Application
\RainLoop\Api::Config();

// returns instance of \SnappyMail\HTTP\CSP
\RainLoop\Api::getCSP(string $sScriptNonce = null);

// returns instance of \MailSo\Log\Logger
\RainLoop\Api::Logger();

// returns string or null
\RainLoop\Api::CreateUserSsoHash(
	string $sEmail,
	string $sPassword,
	array $aAdditionalOptions = array(),
	bool $bUseTimeout = true
)

// returns bool
\RainLoop\Api::ClearUserSsoHash(string $sSsoHash);

// returns bool
\RainLoop\Api::ClearUserData(string $sEmail);

// returns bool
\RainLoop\Api::LogoutCurrentLogginedUser();


// Handle the HTTP request
\RainLoop\Service::Handle();
exit;
```

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

### Use Lightweight Build

Source: https://github.com/the-djmaze/snappymail/blob/master/vendors/openpgp-5/README.md

Import the lightweight build for smaller bundle sizes and lazy loading of non-default curves.

```javascript
import * as openpgp from 'openpgp/lightweight';
```

```javascript
import { generateKey } from 'openpgp/lightweight';
await generateKey({ curve: 'brainpoolP512r1',  userIDs: [{ name: 'Test', email: 'test@test.com' }] });
```

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

### Configure Redis for Caching (MySQL/PostgreSQL)

Source: https://github.com/the-djmaze/snappymail/blob/master/examples/docker/Docker.md

Enables Redis for caching within Snappymail. This configuration is applicable for both MySQL and PostgreSQL setups.

```text
`Cache Redis`: `install`
`Cache Redis`: `enable`
`Cache Redis > host`: `redis`
`Cache Redis > port`: `6379`
```

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

### Get Snappymail Admin Password (Traefik)

Source: https://github.com/the-djmaze/snappymail/blob/master/examples/docker/Docker.md

Retrieves the admin panel password when using Traefik as a reverse proxy. This command targets the Snappymail container.

```sh
docker exec -it $( docker-compose -f docker-compose.traefik.yml ps -q snappymail ) cat /var/lib/snappymail/_data_/_default_/admin_password.txt
```

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

### SnappyMail API Initialization

Source: https://github.com/the-djmaze/snappymail/wiki/API

How to include and initialize the SnappyMail API within a PHP environment.

```APIDOC
## Initialization

### Description
To use SnappyMail as an API, set the environment variable and include the index file.

### Code Example
```php
$_ENV['SNAPPYMAIL_INCLUDE_AS_API'] = true;
require_once '/path/to/snappymail_root/index.php';
```
```

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

### Get Snappymail Admin Password (SQLite)

Source: https://github.com/the-djmaze/snappymail/blob/master/examples/docker/Docker.md

Retrieve the admin panel password when using the SQLite configuration. This command executes a container command to read the password file.

```sh
docker exec -it $( docker-compose -f docker-compose.simple.yml ps -q snappymail ) cat /var/lib/snappymail/_data_/_default_/admin_password.txt
```

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

### Add Snappymail Debian Repository

Source: https://github.com/the-djmaze/snappymail/wiki/Installation-instructions

Add the Snappymail APT repository to your system to install and manage Snappymail using apt. Ensure you have created the necessary keyring and sources list files.

```bash
mkdir -p /usr/share/keyrings/
wget -O- https://snappymail.eu/repository/deb/48208BA13290F3EB.asc | gpg --dearmor > /usr/share/keyrings/snappymail.gpg
```

```bash
deb [signed-by=/usr/share/keyrings/snappymail.gpg] https://snappymail.eu/repository/deb ./
```

```bash
apt update
apt install snappymail
```

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

### Execute release script

Source: https://github.com/the-djmaze/snappymail/blob/master/CONTRIBUTING.md

Run the release script to build the project, with optional flags for specific build targets.

```bash
php release.php
```

```bash
php release.php --aur
```

```bash
php release.php --docker
```

```bash
php release.php --plugins
```

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

### Configure Predis Client with Prefix Option

Source: https://github.com/the-djmaze/snappymail/blob/master/plugins/cache-redis/README.md

Initialize a Predis client with custom connection parameters and a specific key prefix. The prefix is applied to all keys used in commands.

```php
$client = new Predis\Client($parameters, ['prefix' => 'sample:']);
```

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

### Configure PostgreSQL for Snappymail

Source: https://github.com/the-djmaze/snappymail/blob/master/examples/docker/Docker.md

Details for setting up PostgreSQL as the contact storage in Snappymail via the Admin Panel. Assumes PostgreSQL is running.

```text
Type: `PostgresSQL`
Data Source Name (DSN): `host=postgres;port=5432;dbname=snappymail`
User `snappymail`
Password `snappymail`
```

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

### Handle login.credentials.step-2 Hook Parameters

Source: https://github.com/the-djmaze/snappymail/wiki/Developer-Documentation

This hook is called after the initial email check and when the password is provided. It passes both email and password by reference, allowing for modifications.

```PHP
	string &
	$sEmail
	string &
	$sPassword
```

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

### Implementing a Custom OAuth2 Grant Type

Source: https://github.com/the-djmaze/snappymail/blob/master/plugins/login-oauth2/OAuth2/README.md

This example shows how to create a custom grant type by implementing the IGrantType interface. It includes defining the grant type constant and validating mandatory parameters for the grant.

```php
<?php

namespace OAuth2\GrantType;

/**
 * MyCustomGrantType Grant Type
 */
class MyCustomGrantType implements IGrantType
{
    /**
     * Defines the Grant Type
     *
     * @var string  Defaults to 'my_custom_grant_type'.
     */
    const GRANT_TYPE = 'my_custom_grant_type';

    /**
     * Adds a specific Handling of the parameters
     *
     * @return array of Specific parameters to be sent.
     * @param  mixed  $parameters the parameters array (passed by reference)
     */
    public function validateParameters(&$parameters)
    {
        if (!isset($parameters['first_mandatory_parameter']))
        {
            throw new \Exception('The \'first_mandatory_parameter\' parameter must be defined for the Password grant type');
        }
        elseif (!isset($parameters['second_mandatory_parameter']))
        {
            throw new \Exception('The \'seconde_mandatory_parameter\' parameter must be defined for the Password grant type');
        }
    }
}
```

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

### Clone the Knockout repository

Source: https://github.com/the-djmaze/snappymail/blob/master/vendors/knockout/README.md

Use these commands to download the source code from GitHub and navigate into the directory.

```sh
git clone https://github.com/knockout/knockout.git
cd knockout
```

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

### Aggregate Multiple Redis Connections

Source: https://github.com/the-djmaze/snappymail/blob/master/plugins/cache-redis/README.md

Aggregates multiple Redis connections by providing an array of connection parameters and specifying an aggregation option like 'cluster'. This example shows mixing URI strings and named arrays for node configurations.

```php
$client = new Predis\Client([
    'tcp://10.0.0.1?alias=first-node', ['host' => '10.0.0.2', 'alias' => 'second-node'],
], [
    'cluster' => 'predis',
]);
```

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

### Dovecot Master User Entry Example

Source: https://github.com/the-djmaze/snappymail/blob/master/plugins/proxy-auth/README.md

Define a master user in Dovecot's master-users file. This entry specifies the username, encrypted password, and allowed IP networks for the master user. The 'allow_nets' parameter is crucial for restricting access.

```dovecot
admin:PASSWORD::::::allow_nets=local,172.17.0.0/16
```

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

### Create a Plugin with User Settings in PHP

Source: https://context7.com/the-djmaze/snappymail/llms.txt

Implements a plugin class extending AbstractPlugin to register JSON hooks and UI components for user-specific settings.

```php
<?php
// plugins/user-settings-example/index.php

class UserSettingsExamplePlugin extends \RainLoop\Plugins\AbstractPlugin
{
    const
        NAME = 'User Settings Example',
        VERSION = '1.0';

    public function Init(): void
    {
        // Register JSON hooks for getting/saving user settings
        $this->addJsonHook('GetUserSettings', 'doGetUserSettings');
        $this->addJsonHook('SaveUserSettings', 'doSaveUserSettings');

        // Add settings tab UI
        $this->addJs('js/UserSettingsTab.js');
        $this->addTemplate('templates/UserSettingsTab.html');
    }

    /**
     * Get user-specific settings
     */
    public function doGetUserSettings(): array
    {
        // Retrieve settings stored per-user
        $aSettings = $this->getUserSettings();

        return $this->jsonResponse(__FUNCTION__, [
            'signature' => $aSettings['signature'] ?? '',
            'notifications' => $aSettings['notifications'] ?? true,
            'theme' => $aSettings['theme'] ?? 'default'
        ]);
    }

    /**
     * Save user-specific settings
     */
    public function doSaveUserSettings(): array
    {
        $signature = $this->jsonParam('signature', '');
        $notifications = $this->jsonParam('notifications', true);
        $theme = $this->jsonParam('theme', 'default');

        $success = $this->saveUserSettings([
            'signature' => $signature,
            'notifications' => $notifications,
            'theme' => $theme
        ]);

        return $this->jsonResponse(__FUNCTION__, $success);
    }
}
```

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

### Deploy SnappyMail with Docker

Source: https://context7.com/the-djmaze/snappymail/llms.txt

Configuration and commands for deploying SnappyMail using Docker Compose.

```yaml
# docker-compose.yml
version: '2'
services:
  snappymail:
    image: djmaze/snappymail:latest
    ports:
      - 8888:8888
    environment:
      - DEBUG=true
    volumes:
      - snappymail:/var/lib/snappymail
    restart: unless-stopped

volumes:
  snappymail:
    driver: local
```

```bash
# Pull and run
docker pull djmaze/snappymail:latest
docker-compose up -d

# Get admin password
docker exec -it $(docker-compose ps -q snappymail) \
  cat /var/lib/snappymail/_data_/_default_/admin_password.txt

# Access: http://localhost:8888
# Admin:  http://localhost:8888/?admin
```

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

### Import OpenPGP.js in Deno

Source: https://github.com/the-djmaze/snappymail/blob/master/vendors/openpgp-5/README.md

Import the library as an ES6 module from the distribution file.

```javascript
import * as openpgp from './openpgpjs/dist/openpgp.mjs';
```

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

### Run imapsync.php synchronization

Source: https://github.com/the-djmaze/snappymail/wiki/imapsync.php

Execute the synchronization process by providing credentials for both the source and destination IMAP servers.

```bash
/path/to/snappymail/v/0.0.0/imapsync.php \
  --host1 test1.snappymail.eu \
  --user1 test1               \
  --password1 "secret1"       \
  --host2 test2.snappymail.eu \
  --user2 test2               \
  --password2 "secret2"
```

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

### Connect to Redis with Default Parameters

Source: https://github.com/the-djmaze/snappymail/blob/master/plugins/cache-redis/README.md

Connects to Redis using default host (127.0.0.1) and port (6379). The default timeout for connect() is 5 seconds. Use this for basic local Redis instances.

```php
$client = new Predis\Client();
$client->set('foo', 'bar');
$value = $client->get('foo');
```

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

### Configure Redis Replication with Master/Slaves

Source: https://github.com/the-djmaze/snappymail/blob/master/plugins/cache-redis/README.md

Set up a Predis client for replication with a master and multiple slave Redis servers. The client automatically directs read-only commands to slaves and write commands to the master.

```php
$parameters = ['tcp://10.0.0.1?role=master', 'tcp://10.0.0.2', 'tcp://10.0.0.3'];
$options    = ['replication' => 'predis'];

$client = new Predis\Client($parameters, $options);
```

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

### Clone the repository

Source: https://github.com/the-djmaze/snappymail/blob/master/CONTRIBUTING.md

Clone the SnappyMail repository to your local machine.

```bash
git clone git@github.com:USERNAME/snappymail.git snappymail
```

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

### Configure Application Settings

Source: https://context7.com/the-djmaze/snappymail/llms.txt

Main configuration file for SnappyMail located in data/_data_/_default_/configs/.

```ini
; application.ini - Located in data/_data_/_default_/configs/

[webmail]
title = "SnappyMail Webmail"
loading_description = "SnappyMail"
favicon_url = ""
theme = "Default"
allow_themes = On
language = "en"
allow_languages_on_settings = On
allow_additional_accounts = On
allow_additional_identities = On
messages_per_page = 20
message_read_delay = 5
min_refresh_interval = 5
attachment_size_limit = 25

[contacts]
enable = On
allow_sync = On
sync_interval = 20
type = "mysql"
pdo_dsn = "host=127.0.0.1;port=3306;dbname=snappymail"
pdo_user = "snappymail"
pdo_password = "your-password"
suggestions_limit = 20

[security]
allow_admin_panel = On
admin_login = "admin"
admin_password = "$2y$10$..."
force_https = Off
openpgp = On
gnupg = On
content_security_policy = ""
encrypt_cipher = "aes-256-cbc-hmac-sha1"

[login]
default_domain = "example.com"
allow_languages_on_login = On
determine_user_language = On
sign_me_auto = "DefaultOff"
fault_delay = 5

[plugins]
enable = On
enabled_list = "avatars,change-password"

[logs]
enable = On
path = "/var/log/snappymail/"
level = 4
filename = "log-{date:Y-m-d}.txt"
auth_logging = On
auth_logging_filename = "fail2ban/auth-{date:Y-m-d}.txt"

[cache]
enable = On
http = On
http_expires = 3600
server_uids = On

[debug]
enable = Off
javascript = Off
css = Off
```

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

### Implement Plugin JavaScript Integration

Source: https://context7.com/the-djmaze/snappymail/llms.txt

Provides client-side logic for managing settings view models, listening to application events, and interacting with the SnappyMail API.

```javascript
// plugins/my-plugin/js/my-plugin.js

(function() {
    'use strict';

    // Add a user settings view
    class MyPluginSettings {
        constructor() {
            this.signature = ko.observable('');
            this.notifications = ko.observable(true);
            this.loading = ko.observable(false);
        }

        // Load settings from server
        load() {
            this.loading(true);
            rl.pluginRemoteRequest(
                (result, data) => {
                    this.loading(false);
                    if (result === rl.Enums.StorageResultType.Success && data.Result) {
                        this.signature(data.Result.signature || '');
                        this.notifications(data.Result.notifications !== false);
                    }
                },
                'GetUserSettings'
            );
        }

        // Save settings to server
        save() {
            this.loading(true);
            rl.pluginRemoteRequest(
                (result, data) => {
                    this.loading(false);
                    if (result === rl.Enums.StorageResultType.Success) {
                        // Show success notification
                        console.log('Settings saved successfully');
                    }
                },
                'SaveUserSettings',
                {
                    signature: this.signature(),
                    notifications: this.notifications()
                }
            );
        }
    }

    // Register the settings tab (for user area)
    rl.addSettingsViewModel(
        MyPluginSettings,
        'MyPluginSettingsTab',      // Template name
        'My Plugin',                 // Tab label
        'my-plugin'                  // Route
    );

    // Listen to custom events
    addEventListener('mailbox.message.show', event => {
        console.log('Message shown:', event.detail.folder, event.detail.uid);
    });

    // Listen to view model creation
    addEventListener('rl-view-model.create', event => {
        const vm = event.detail;
        console.log('View model created:', vm.constructor.name);
    });

    // Modify compose editor toolbar
    addEventListener('squire-toolbar', event => {
        const { squire, actions } = event.detail;
        // Add custom button to toolbar
        actions['custom'] = {
            'my-button': {
                html: 'Custom',
                cmd: () => squire.insertHTML('<b>Custom text</b>')
            }
        };
    });

    // Use the fetch API wrapper
    async function fetchData() {
        try {
            const response = await rl.fetchJSON('/api/custom-endpoint', {
                method: 'POST'
            }, { param: 'value' });
            console.log('Response:', response);
        } catch (error) {
            console.error('Fetch error:', error);
        }
    }

    // Access application settings
    const language = rl.settings.get('Language');
    const theme = rl.settings.get('Theme');

    // Check if in admin area
    if (rl.adminArea()) {
        console.log('Running in admin panel');
    }

})();
```

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

### Command Line Compilation with Direct Input

Source: https://github.com/the-djmaze/snappymail/blob/master/snappymail/v/0.0.0/app/libraries/lessphp/README.md

Use the `-r` flag to provide LESS code directly as an argument or from standard input.

```bash
$ plessc -r "my less code here"

```

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

### Apache VirtualHost Configuration

Source: https://github.com/the-djmaze/snappymail/wiki/Installation-instructions

Apache configuration using macros to define a VirtualHost for SnappyMail with security headers and directory restrictions.

```apache
Listen 2096
<Macro VHWebMail $host>
	<VirtualHost *:2096>
		ServerName $host
		ServerAdmin webmaster@$host
		DocumentRoot /home/snappymail/public_html

# Security headers
Header always set Strict-Transport-Security "max-age=31536000"
Header always set X-Content-Type-Options "nosniff"
Header always set X-Xss-Protection "1; mode=block"
Header always set Referrer-Policy "no-referrer"
Header always set X-Frame-Options "SAMEORIGIN"
	
#		RemoveHandler cgi-script .cgi .pl .plx .ppl .perl
		UseCanonicalName Off
		<Directory /home/snappymail/public_html>
			Options -ExecCGI -Includes -Indexes
```

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

### Configure SnappyMail Application Logs

Source: https://github.com/the-djmaze/snappymail/blob/master/fail2ban/README.md

Update the application.ini file to enable authentication logging for Fail2ban monitoring.

```ini
[logs]
auth_logging = On
auth_logging_filename = "fail2ban/auth-fail.log"
auth_logging_format = "[{date:Y-m-d H:i:s T}] Auth failed: ip={request:ip} user={imap:login} host={imap:host} port={imap:port}"
```

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

### Deploy SnappyMail with MySQL

Source: https://context7.com/the-djmaze/snappymail/llms.txt

Docker Compose configuration for SnappyMail with a persistent MySQL database for contact storage.

```yaml
# docker-compose.mysql.yml
version: '3'
services:
  snappymail:
    image: djmaze/snappymail:latest
    ports:
      - 8888:8888
    volumes:
      - snappymail:/var/lib/snappymail
    depends_on:
      - db
    restart: unless-stopped

  db:
    image: mysql:5.7
    restart: always
    environment:
      - MYSQL_ROOT_PASSWORD=root
      - MYSQL_USER=snappymail
      - MYSQL_PASSWORD=snappymail
      - MYSQL_DATABASE=snappymail
    volumes:
      - mysql:/var/lib/mysql

volumes:
  snappymail:
  mysql:
```

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

### Command Line Compilation

Source: https://github.com/the-djmaze/snappymail/blob/master/snappymail/v/0.0.0/app/libraries/lessphp/README.md

Compile LESS to CSS from the command line. Output is directed to standard output by default.

```bash
$ plessc input.less > output.css

```

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

### Configure Redis Replication with Sentinel

Source: https://github.com/the-djmaze/snappymail/blob/master/plugins/cache-redis/README.md

Configure the Predis client to use Redis Sentinel for robust high availability and service discovery. Provide connection parameters for Sentinel instances and the service name.

```php
$sentinels = ['tcp://10.0.0.1', 'tcp://10.0.0.2', 'tcp://10.0.0.3'];
$options   = ['replication' => 'sentinel', 'service' => 'mymaster'];

$client = new Predis\
Client($sentinels, $options);
```

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

### Define Plugin Information

Source: https://github.com/the-djmaze/snappymail/wiki/Developer-Documentation

Declare essential metadata for your plugin, such as name, author, version, and description. This information is displayed in the SnappyMail Admin Panel.

```PHP
	const
		NAME     = 'Avatars',
		AUTHOR   = 'SnappyMail',
		URL      = 'https://snappymail.eu/',
		VERSION  = '1.5',
		RELEASE  = '2022-12-15',
		REQUIRED = '2.23.0',
		CATEGORY = 'Contacts',
		LICENSE  = 'MIT',
		DESCRIPTION = 'Show graphic of sender in message and messages list (supports BIMI, Gravatar and identicon, Contacts is still TODO)';
```

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

### Implement Single Sign-On (SSO)

Source: https://context7.com/the-djmaze/snappymail/llms.txt

Methods for generating SSO hashes to authenticate users from external applications and managing user sessions.

```php
<?php
$_ENV['SNAPPYMAIL_INCLUDE_AS_API'] = true;
require_once '/path/to/snappymail/index.php';

// Create an SSO hash for a user
$email = 'user@example.com';
$password = 'user-password';
$additionalOptions = [
    'Language' => 'en',
    'Theme' => 'Default'
];
$useTimeout = true; // Hash expires after timeout

$ssoHash = \RainLoop\Api::CreateUserSsoHash(
    $email,
    $password,
    $additionalOptions,
    $useTimeout
);

if ($ssoHash) {
    // Redirect user to SnappyMail with SSO
    $webmailUrl = 'https://webmail.example.com/?Sso&hash=' . $ssoHash;
    header('Location: ' . $webmailUrl);
    exit;
}

// Clear SSO hash after use (optional, for security)
\RainLoop\Api::ClearUserSsoHash($ssoHash);

// Clear all user data (contacts, settings, cache)
\RainLoop\Api::ClearUserData('user@example.com');

// Logout the currently logged-in user
\RainLoop\Api::LogoutCurrentLogginedUser();
```

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

### Configure Predis Client for Traditional Clustering

Source: https://github.com/the-djmaze/snappymail/blob/master/plugins/cache-redis/README.md

Set up a Predis client to work in a traditional client-side sharding cluster mode. This requires a list of node addresses and the 'predis' cluster type.

```php
$parameters = ['tcp://10.0.0.1', 'tcp://10.0.0.2', 'tcp://10.0.0.3'];
$options    = ['cluster' => 'predis'];

$client = new Predis\Client($parameters);
```

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

### Initialize SnappyMail API

Source: https://context7.com/the-djmaze/snappymail/llms.txt

This section covers how to include SnappyMail as a library in your PHP application to access core services like Actions, Config, and Logger.

```APIDOC
## Initialize SnappyMail API

### Description
Include SnappyMail as a library in your PHP application for programmatic access to the application's core instances.

### Usage
```php
$_ENV['SNAPPYMAIL_INCLUDE_AS_API'] = true;
require_once '/path/to/snappymail_root/index.php';

$actions = \RainLoop\Api::Actions();
$config = \RainLoop\Api::Config();
$logger = \RainLoop\Api::Logger();
```
```

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

### Load OpenPGP.js in Browser

Source: https://github.com/the-djmaze/snappymail/blob/master/vendors/openpgp-5/README.md

Methods for including the library in browser environments using standard script tags or ES6 modules.

```html
<script src="openpgp.min.js"></script>
```

```html
<script type="module">
import * as openpgp from './openpgp.min.mjs';
</script>
```