WildDuck

https://github.com/zone-eu/wildduck
Admin
WildDuck is a scalable no-SPOF IMAP/POP3 mail server built with Node.js and MongoDB that provides...
Tokens:65,704
Snippets:683
Trust Score:9.6
Update:3 months ago
Show doc for...
Tokens:
Raw
### Start the Server

Source: https://github.com/zone-eu/wildduck/blob/master/CLAUDE.md

Starts the WildDuck mail server application.

```bash
# Start the server
npm start
```

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

### Download and Execute WildDuck Install Script

Source: https://github.com/zone-eu/wildduck/blob/master/setup/README.md

Fetches the WildDuck installation script from GitHub and executes it. Run this command as root.

```bash
wget -O - https://raw.githubusercontent.com/zone-eu/wildduck/master/setup/get_install.sh | bash
```

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

### Install PST Utilities and ISync

Source: https://github.com/zone-eu/wildduck/wiki/migration-guide

Installs necessary tools for converting PST files and synchronizing mail.

```bash
sudo apt-get install pst-utils
sudo apt-get install isync
```

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

### Run WildDuck Install Script with Domains

Source: https://github.com/zone-eu/wildduck/blob/master/setup/README.md

Executes the downloaded install script. Replace 'mydomain.com' with your email domain and 'mail.mydomain.com' with your server's hostname. Ensure the hostname points to your server and the MX records are configured correctly.

```bash
./install.sh mydomain.com mail.mydomain.com
```

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

### Example Git Config File

Source: https://github.com/zone-eu/wildduck/wiki/Updating-wildduck-via-git

This is an example of a complete `config` file for a Git repository with a separate git directory, including the necessary fetch refspec.

```ini
[core]
	repositoryformatversion = 0
	filemode = true
	bare = true
[remote "origin"]
	fetch = +refs/heads/*:refs/remotes/origin/*
	url = git://github.com/zone-eu/zone-mta-template.git
```

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

### Import Maildir to WildDuck (Example User)

Source: https://github.com/zone-eu/wildduck/wiki/migration-guide

Provides an example of importing a specific user's maildir data into WildDuck.

```bash
./bin/import-maildir user@example.com:/var/mail/user_example.com/
```

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

### API Test Example

Source: https://github.com/zone-eu/wildduck/blob/master/CLAUDE.md

Example of an API integration test using Supertest. Requires the server to be running. Includes setup and cleanup logic.

```javascript
const supertest = require('supertest');
const server = supertest.agent(`http://127.0.0.1:${config.api.port}`);

describe('Users API', function() {
    this.timeout(10000);
    let userId;

    before(async () => {
        // Create test data
        const res = await server.post('/users').send({...}).expect(200);
        userId = res.body.id;
    });

    after(async () => {
        // Cleanup
        await server.delete(`/users/${userId}`).expect(200);
    });

    it('should GET /users/:user expect success', async () => {
        const response = await server.get(`/users/${userId}`).expect(200);
        expect(response.body.success).to.be.true;
    });
});
```

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

### Setup Autoreply

Source: https://github.com/zone-eu/wildduck/wiki/API-Docs

Sets up an autoreply for a user.

```APIDOC
## PUT /users/{user}/autoreply

### Description
Sets up an autoreply for a user.

### Method
PUT

### Endpoint
/users/{user}/autoreply
```

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

### Run WildDuck with Default Configuration

Source: https://github.com/zone-eu/wildduck/blob/master/docs/general/install.md

Start the WildDuck server using the default configuration file.

```bash
node server.js
```

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

### User Update Event Stream Example

Source: https://github.com/zone-eu/wildduck/wiki/API-Docs

Example of data received from the user update event stream, showing message creation and mailbox creation events.

```text
data: {"command":"EXISTS", "message":"596e0703f0bdd512aeac3600", "mailbox":"596c9c37ef2213165daadc65",...}
id: 596e0703f0bdd512aeac3605

data: {"command":"CREATE","mailbox":"596e09853f845a14f3620b5c","name":"My Mail",...}
id: 596e09853f845a14f3620b5d
```

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

### Unit Test Example

Source: https://github.com/zone-eu/wildduck/blob/master/CLAUDE.md

Example of a unit test using Chai for assertions. Does not require the server to be running.

```javascript
const expect = require('chai').expect;
const parser = require('../lib/handler/imap-parser');

describe('IMAP Parser', () => {
    it('should parse command', () => {
        const result = parser('A1 LOGIN user pass');
        expect(result.command).to.equal('LOGIN');
    });
});
```

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

### Install WildDuck Production Dependencies

Source: https://github.com/zone-eu/wildduck/blob/master/docs/general/install.md

Install the necessary Node.js dependencies for WildDuck in production mode.

```bash
$ npm install --production
```

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

### Clone and Install import-maildir Tool

Source: https://github.com/zone-eu/wildduck/wiki/migration-guide

Clones the import-maildir tool from GitHub and installs its production dependencies using npm.

```bash
$ git clone git://github.com/nodemailer/import-maildir.git
$ cd import-maildir
$ npm install --production
```

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

### API Authentication Example

Source: https://github.com/zone-eu/wildduck/wiki/API-Docs

Demonstrates how to authenticate API requests using an access token. The token must be included as a query argument.

```bash
curl "http://localhost:8080/users?query=testuser01&accessToken=secrettoken"
```

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

### Run WildDuck with Custom Configuration

Source: https://github.com/zone-eu/wildduck/blob/master/docs/general/install.md

Start the WildDuck server, overriding default configuration options with a custom TOML file.

```bash
node server.js --config=/etc/wildduck.toml
```

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

### Get Filter Details Response

Source: https://github.com/zone-eu/wildduck/wiki/API-Docs

Example response for retrieving filter details, showing its ID, name, creation date, and specific query/action settings.

```json
{
    "success": true,
    "id": "59759c440e1d676f15e76b5f",
    "name": "Flag messages from abc",
    "created": "2017-07-24T07:05:40.355Z",
    "query_from": "abc",
    "action_flag": true
}
```

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

### Install PST Utilities and ISync

Source: https://github.com/zone-eu/wildduck/blob/master/docs/general/migration-guide.md

Installs necessary tools for converting Outlook .pst files to maildir format. These commands are typically run on a Debian-based system.

```bash
sudo apt-get install pst-utils
sudo apt-get install isync
mkdir anon_maildir; cd anon_maildir
readpst -M anon_inbox.pst
```

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

### Fetch Next Page API Request

Source: https://github.com/zone-eu/wildduck/wiki/API-Docs

Example of an HTTP GET request to fetch the next page of results using the 'nextCursor', 'page', and 'limit' parameters.

```http
GET /users/{user}/mailboxes/{mailbox}/messages?next={nextCursor}&page={page+1}&limit=20
```

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

### DKIM DNS Record Example

Source: https://github.com/zone-eu/wildduck/wiki/migration-guide

Example of a DKIM DNS record configuration.

```dns
jun2018._domainkey .yourdomain.com
v=DKIM1;p=MIIBIjANBgkqhkiG9...
```

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

### Setup Autoreply Message

Source: https://github.com/zone-eu/wildduck/wiki/API-Docs

Use this endpoint to configure or modify an autoreply message for a user. You can partially update fields like status, subject, text, html, start, and end times.

```bash
curl -XPUT "http://localhost:8080/users/5971da1754cfdc7f0983b2ec/autoreply" -H 'content-type: application/json' -d '{
  "status": true,
  "subject": "Out of office",
  "text": "I'm out of office this week",
  "start": "2017-11-15T00:00:00.000Z",
  "end": "2017-11-19T00:00:00.000Z",
}'
```

```json
{
    "success": true
}
```

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

### Example Parsed IMAP Command Result

Source: https://github.com/zone-eu/wildduck/blob/master/imap-core/lib/handler/README.md

Shows the resulting JSON object after parsing the example IMAP command string.

```json
{
    "tag": "A1",
    "command": "FETCH",
    "attributes": [
        [
            {
                "type": "SEQUENCE",
                "value": "*:4"
            },
            {
                "type": "ATOM",
                "value": "BODY",
                "section": [
                    {
                        "type": "ATOM",
                        "value": "HEADER.FIELDS"
                    },
                    [
                        {
                            "type": "LITERAL",
                            "value": "Date"
                        },
                        {
                            "type": "ATOM",
                            "value": "Subject"
                        }
                    ]
                ],
                "partial": [
                    12,
                    45
                ]
            },
            {
                "type": "ATOM",
                "value": "UID"
            }
        ]
    ]
}
```

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

### Handler Async Pattern Example

Source: https://github.com/zone-eu/wildduck/blob/master/CLAUDE.md

Demonstrates the dual callback and promise-based API pattern supported by WildDuck handlers.

```javascript
// Callback style
handler.resolveAddress(address, options, callback);
// Promise style (prefix with 'async')
await handler.asyncResolveAddress(address, options);
```

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

### Setup Autoreply

Source: https://github.com/zone-eu/wildduck/wiki/API-Docs

Sets up or updates an autoreply message for a user. This can be done partially, updating only specific fields.

```APIDOC
## PUT /users/{user}/autoreply

### Description
Sets up or updates an autoreply message for the user.

### Method
PUT

### Endpoint
/users/{user}/autoreply

### Parameters
#### Path Parameters
- **user** (string) - Required - The ID of the user.

#### Request Body
- **status** (boolean) - Optional - Indicates if autoreply messages should be sent (true) or not (false).
- **subject** (string) - Optional - The subject line of the autoreply message.
- **text** (string) - Optional - The text body of the autoreply message.
- **html** (string) - Optional - The HTML body of the autoreply message.
- **start** (string) - Optional - The start time of the autoreply (ISO 8601 format).
- **end** (string) - Optional - The end time of the autoreply (ISO 8601 format).

### Request Example
```json
{
  "status": true,
  "subject": "Out of office",
  "text": "I'm out of office this week",
  "start": "2017-11-15T00:00:00.000Z",
  "end": "2017-11-19T00:00:00.000Z"
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.

#### Response Example
```json
{
    "success": true
}
```
```

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

### WildDuck Checkout Error Example

Source: https://github.com/zone-eu/wildduck/wiki/Updating-wildduck-via-git

This example demonstrates a common error when attempting to checkout a commit hash without first fetching the origin. Ensure 'git fetch origin' is performed before fetching a specific commit.

```bash
(deploy) $ git --git-dir=/var/opt/wildduck.git --work-tree=/opt/wildduck checkout 538da537ca3cef0bbd714da70085cfd4cc734b49
fatal: reference is not a tree: 538da537ca3cef0bbd714da70085cfd4cc734b49
```

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

### Setup 2FA

Source: https://github.com/zone-eu/wildduck/wiki/API-Docs

Sets up Time-based One-Time Password (TOTP) for two-factor authentication.

```APIDOC
## POST /users/{user}/2fa/totp/setup

### Description
Sets up Time-based One-Time Password (TOTP) for two-factor authentication for a user.

### Method
POST

### Endpoint
/users/{user}/2fa/totp/setup

### Parameters
#### Path Parameters
- **user** (string) - Required - The username or ID of the user.

#### Response
Returns a secret key and a QR code URL for setting up the authenticator app.
```

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

### Setup 2FA TOTP

Source: https://github.com/zone-eu/wildduck/wiki/API-Docs

Prepares a user to support 2FA TOTP tokens. This call generates a QR code for the user to scan with their authenticator app.

```APIDOC
## POST /users/{user}/2fa/totp/setup

### Description
This call prepares the user to support 2FA tokens. If 2FA is already enabled then this call fails.

### Method
POST

### Endpoint
/users/{user}/2fa/totp/setup

### Parameters
#### Path Parameters
- **user** (string) - Required - The ID of the user

#### Request Body
- **issuer** (string) - Optional - The name to be shown in the Authenticator App
- **fresh** (boolean) - Optional - If true then generates a new seed even if an old one already exists
- **sess** (string) - Optional - An optional string of user session to be stored in security log
- **ip** (string) - Optional - The IP address the request was made from

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful (should be `true`)
- **qrcode** (string) - The data URL for the 2FA QR-code. The user must scan the code and return the token with a PUT call

### Request Example
```json
{
  "issuer": "testikas",
  "ip": "192.168.10.10"
}
```

### Response Example
```json
{
    "success": true,
    "qrcode": "data:image/png;base64,iVBORw0KGgoAAAANSU..."
}
```
```

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

### Example IMAP Command Compilation

Source: https://github.com/zone-eu/wildduck/blob/master/imap-core/lib/handler/README.md

Demonstrates compiling a command object with SECTION and TEXT attributes into an IMAP command string and piping it to standard output.

```javascript
let command = {
    tag: "*",
    command: "OK",
    attributes: [
        {
            type: "SECTION",
            section: [
                {type: "ATOM", value: "ALERT"}
            ]
        },
        {type:"TEXT", value: "NB! The server is shutting down"}
    ]
};

imapHandler.compileStream(command).pipe(process.stdout);
```

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

### Run WildDuck Docker Container with Default Configuration

Source: https://github.com/zone-eu/wildduck/wiki/Docker

This command starts the WildDuck container using its default configuration. It may fail if MongoDB and Redis are not accessible on localhost.

```bash
docker run nodemailer/wildduck
```

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

### Setup TOTP 2FA Response

Source: https://github.com/zone-eu/wildduck/wiki/API-Docs

Successful response after setting up TOTP 2FA, containing the QR code data URL for the user to scan.

```json
{
    "success": true,
    "qrcode": "data:image/png;base64,iVBORw0KGgoAAAANSU..."
}
```

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

### User Quota Reset Response

Source: https://github.com/zone-eu/wildduck/wiki/API-Docs

Example JSON response indicating a successful user quota reset operation.

```json
{
    "success": true,
    "storageUsed": 128
}
```

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

### Update haraka-plugin-wildduck

Source: https://github.com/zone-eu/wildduck/wiki/Updating-wildduck-via-git

Fetches the latest code for haraka-plugin-wildduck, installs production dependencies, and restarts the Haraka service. Ensure you are running these commands as the 'deploy' user.

```bash
(root) $ sudo su deploy
(deploy) $ cd /var/opt/haraka-plugin-wildduck.git/
(deploy) $ git --git-dir=/var/opt/haraka-plugin-wildduck.git --work-tree=/opt/haraka/plugins/wildduck fetch origin
(deploy) $ git --git-dir=/var/opt/haraka-plugin-wildduck.git --work-tree=/opt/haraka/plugins/wildduck checkout 14db1ceed857f8616094cfd2f52b6b58bf413173
(deploy) $ cd /opt/haraka/plugins/wildduck/
(deploy) $ npm install --unsafe-perm --production
(deploy) $ exit
(userr) $ systemctl restart haraka
```

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

### List Filters Response

Source: https://github.com/zone-eu/wildduck/wiki/API-Docs

Example response when listing filters, showing filter ID, name, query criteria, and actions.

```json
{
    "success": true,
    "results": [
        {
            "id": "59759c440e1d676f15e76b5f",
            "name": "Flag messages from abc",
            "query": [["from", "(abc)"]],
            "action": [["flag it"]],
            "created": "2017-07-24T07:05:40.355Z"
        }
    ]
}
```

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

### Fetch Previous Page API Request

Source: https://github.com/zone-eu/wildduck/wiki/API-Docs

Example of an HTTP GET request to fetch the previous page of results using the 'previousCursor', 'page', and 'limit' parameters.

```http
GET /users/{user}/mailboxes/{mailbox}/messages?previous={previousCursor}&page={page-1}&limit=20
```

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

### Configure POP3 Server with Connection Handlers

Source: https://github.com/zone-eu/wildduck/blob/master/docs/in-depth/connection-management.md

Set up a POP3 server instance with onConnect and onClose handlers for managing client sessions. The callback must be invoked to allow or deny the connection.

```javascript
const POP3Server = require('wildduck/lib/pop3/server');

const server = new POP3Server({
    onConnect: (session, callback) => {
        // Connection logic
        callback(); // Allow connection
    },
    onClose: (session) => {
        // Cleanup logic
    }
});
```

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

### Setup TOTP 2FA

Source: https://github.com/zone-eu/wildduck/wiki/API-Docs

Prepares a user for 2FA by generating a QR code for authenticator apps. This call fails if 2FA is already enabled. Ensure the 'user' ID is provided.

```bash
curl -XPOST "http://localhost:8080/users/5971da1754cfdc7f0983b2ec/2fa/totp/setup" -H 'content-type: application/json' -d '{
  "issuer": "testikas",
  "ip": "192.168.10.10"
}'
```

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

### Run WildDuck Docker with Custom CMD_ARGS

Source: https://github.com/zone-eu/wildduck/wiki/Docker

Configure WildDuck by passing custom arguments via CMD_ARGS to set MongoDB/Redis hosts, FQDN, and mail domain.

```bash
FQDN='example.com'
MAIL_DOMAIN='mail.example.com'
docker run --env CMD_ARGS="\
    --dbs.mongo=mongodb://mongo:27017/ \
    --dbs.redis=redis://redis:6379/3 \
    --smtp.setup.hostname=$FQDN \
    --log.gelf.hostname=$FQDN \
    --imap.setup.hostname=$FQDN \
    --emailDomain=$MAIL_DOMAIN" \
    nodemailer/wildduck 
```

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

### haraka-plugin-wildduck Initialization

Source: https://github.com/zone-eu/wildduck/blob/master/CLAUDE.md

Shows how to import and instantiate handlers from the WildDuck library within the haraka-plugin-wildduck for incoming mail processing.

```javascript
const FilterHandler = require('@zone-eu/wildduck/lib/filter-handler');
const UserHandler = require('@zone-eu/wildduck/lib/user-handler');
const Maildropper = require('@zone-eu/wildduck/lib/maildropper');
// Stores messages via: filterHandler.storeMessage(userData, options)
```

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

### Run Full Test Suite

Source: https://github.com/zone-eu/wildduck/blob/master/CLAUDE.md

Execute all tests, including database cleanup, Redis flushing, linting, server startup, and all test suites.

```bash
npm test
```

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

### Run Wildduck Docker with Custom Environment Variables

Source: https://github.com/zone-eu/wildduck/blob/master/docs/in-depth/docker.md

Configure Wildduck by passing environment variables to the container. This example sets custom MongoDB and Redis hosts, FQDN, and email domain.

```bash
FQDN='example.com'
MAIL_DOMAIN='mail.example.com'
docker run \
-e APPCONF_dbs_mongo='mongodb://mongo:27017/' \
-e APPCONF_dbs_redis='redis://redis:6379/3' \
-e APPCONF_smtp_setup_hostname=$FQDN \
-e APPCONF_log_gelf_hostname=$FQDN \
-e APPCONF_imap_setup_hostname=$FQDN \
-e APPCONF_emailDomain=$MAIL_DOMAIN \
nodemailer/wildduck
```

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

### Import Maildir to WildDuck (Single User)

Source: https://github.com/zone-eu/wildduck/wiki/migration-guide

Starts the import process for a single user's maildir data into WildDuck. Ensure the user account already exists in WildDuck.

```bash
./bin/import-maildir userid:maildirpath
```

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

### Search Messages in MongoDB

Source: https://github.com/zone-eu/wildduck/blob/master/docs/in-depth/command-line.md

This example demonstrates how to search for messages in MongoDB containing specific Chinese characters. It shows the MongoDB shell commands and an example of the output format.

```mongo
mongo
> use wildduck
> db.
messages.
find({'headers.value': /[姚轉]/ }).
ttoArray().
map(doc => '/users/' + doc.user.str + '/mailboxes/' + doc.mailbox.str + '/messages/' + doc.uid )
```

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

### Show Effective Configuration

Source: https://github.com/zone-eu/wildduck/blob/master/CLAUDE.md

Displays the current effective configuration settings of the server.

```bash
# Show effective configuration
npm run printconf
```

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

### Get Attachment

Source: https://github.com/zone-eu/wildduck/wiki/API-Docs

Retrieves a specific attachment from a message.

```APIDOC
## GET /users/{user}/mailboxes/{mailbox}/messages/{message}/attachments/{attachment}

### Description
Retrieves a specific attachment from a message.

### Method
GET

### Endpoint
/users/{user}/mailboxes/{mailbox}/messages/{message}/attachments/{attachment}
```

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

### Get one address

Source: https://github.com/zone-eu/wildduck/wiki/API-Docs

Returns data about a specific address.

```APIDOC
## GET /users/{user}/addresses/{address}

### Description
Returns data about a specific address.

### Method
GET

### Endpoint
/users/{user}/addresses/{address}

### Parameters
#### Path Parameters
- **user** (string) - Required - The ID of the user
- **address** (string) - Required - The ID of the address

### Request Example
```
curl "http://localhost:8080/users/59467f27535f8f0f067ba8e6/addresses/596c9c37ef2213165daadc6b"
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful
- **id** (string) - The unique identifier for the address
- **address** (string) - The email address
- **main** (boolean) - Indicates if this is the default address for the user
- **created** (string) - The timestamp when the address was created

#### Response Example
{
    "success": true,
    "id": "596c9c37ef2213165daadc6b",
    "address": "testuser@example.com",
    "main": true,
    "created": "2017-07-17T11:15:03.841Z"
}
```

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

### Get Filter Details

Source: https://github.com/zone-eu/wildduck/wiki/API-Docs

Retrieves the details of a specific filter.

```APIDOC
## GET /users/{user}/filters/{filter}

### Description
Retrieves the details of a specific filter.

### Method
GET

### Endpoint
/users/{user}/filters/{filter}
```

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

### Configure IMAP Server with Connection Handlers

Source: https://github.com/zone-eu/wildduck/blob/master/docs/in-depth/connection-management.md

Set up an IMAP server instance with onConnect and onClose handlers for managing client sessions. The callback must be invoked to allow or deny the connection.

```javascript
const { IMAPServer } = require('wildduck/imap-core');

const server = new IMAPServer({
    onConnect: (session, callback) => {
        // Connection logic
        callback(); // Allow connection
    },
    onClose: (session) => {
        // Cleanup logic
    }
});
```

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

### Get message attachment

Source: https://github.com/zone-eu/wildduck/wiki/API-Docs

Retrieves a specific attachment from a message.

```APIDOC
## GET /users/{user}/mailboxes/{mailbox}/messages/{message}/attachments/{attachment}

### Description
Retrieves a specific attachment from a message.

### Method
GET

### Endpoint
/users/{user}/mailboxes/{mailbox}/messages/{message}/attachments/{attachment}

### Parameters
#### Path Parameters
- **user** (string) - Required - The username or ID of the user.
- **mailbox** (string) - Required - The name of the mailbox containing the message.
- **message** (string) - Required - The ID of the message.
- **attachment** (string) - Required - The filename or ID of the attachment.
```

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

### Create a New User

Source: https://github.com/zone-eu/wildduck/wiki/API-Docs

Use this endpoint to create a new user. Specify username, password, and optionally an address, forwarding rules, storage quota, and PGP keys.

```bash
curl -XPOST "http://localhost:8080/users" -H 'content-type: application/json' -d '{
  "username": "testuser",
  "password": "secretpass",
  "address": "testuser@example.com",
  "ip": "192.168.10.10"
}'
```

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

### Get one mailbox

Source: https://github.com/zone-eu/wildduck/wiki/API-Docs

Retrieves details for a specific mailbox.

```APIDOC
## GET /users/{user}/mailboxes/{mailbox}

### Description
Retrieves details for a specific mailbox.

### Method
GET

### Endpoint
/users/{user}/mailboxes/{mailbox}

### Parameters
#### Path Parameters
- **user** (string) - Required - The username or ID of the user.
- **mailbox** (string) - Required - The name of the mailbox (e.g., 'INBOX').
```

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

### Get one user

Source: https://github.com/zone-eu/wildduck/wiki/API-Docs

Retrieves details for a specific user.

```APIDOC
## GET /users/{user}

### Description
Retrieves details for a specific user identified by their username or ID.

### Method
GET

### Endpoint
/users/{user}

### Parameters
#### Path Parameters
- **user** (string) - Required - The username or ID of the user.
```

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

### Generate API Documentation

Source: https://github.com/zone-eu/wildduck/blob/master/CLAUDE.md

Generates API documentation for the project.

```bash
# Generate API documentation
npm run apidoc
```

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

### zonemta-wildduck Initialization

Source: https://github.com/zone-eu/wildduck/blob/master/CLAUDE.md

Demonstrates the import and instantiation of WildDuck handlers within the zonemta-wildduck plugin for outgoing mail processing.

```javascript
const MessageHandler = require('@zone-eu/wildduck/lib/message-handler');
const UserHandler = require('@zone-eu/wildduck/lib/user-handler');
const DkimHandler = require('@zone-eu/wildduck/lib/dkim-handler');
// Uploads to Sent folder, retrieves DKIM keys, validates users
```

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

### Get message source

Source: https://github.com/zone-eu/wildduck/wiki/API-Docs

Retrieves the raw source of a specific message.

```APIDOC
## GET /users/{user}/mailboxes/{mailbox}/messages/{message}/message.eml

### Description
Retrieves the raw source of a specific message in .eml format.

### Method
GET

### Endpoint
/users/{user}/mailboxes/{mailbox}/messages/{message}/message.eml

### Parameters
#### Path Parameters
- **user** (string) - Required - The username or ID of the user.
- **mailbox** (string) - Required - The name of the mailbox containing the message.
- **message** (string) - Required - The ID of the message.
```

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

### Get message details

Source: https://github.com/zone-eu/wildduck/wiki/API-Docs

Retrieves the full details of a specific message.

```APIDOC
## GET /users/{user}/mailboxes/{mailbox}/messages/{message}

### Description
Retrieves the full details of a specific message.

### Method
GET

### Endpoint
/users/{user}/mailboxes/{mailbox}/messages/{message}

### Parameters
#### Path Parameters
- **user** (string) - Required - The username or ID of the user.
- **mailbox** (string) - Required - The name of the mailbox containing the message.
- **message** (string) - Required - The ID of the message.
```

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

### Get one address

Source: https://github.com/zone-eu/wildduck/wiki/API-Docs

Retrieves details for a specific email address.

```APIDOC
## GET /users/{user}/addresses/{address}

### Description
Retrieves details for a specific email address.

### Method
GET

### Endpoint
/users/{user}/addresses/{address}

### Parameters
#### Path Parameters
- **user** (string) - Required - The username or ID of the user.
- **address** (string) - Required - The email address or its ID.
```

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

### Get filter details

Source: https://github.com/zone-eu/wildduck/wiki/API-Docs

Retrieves the details of a specific message filter for a user.

```APIDOC
## GET /users/{user}/filters/{filter}

### Description
Returns data about a specific filter.

### Method
GET

### Endpoint
/users/{user}/filters/{filter}

### Parameters
#### Path Parameters
- **user** (string) - Required - The ID of the user.
- **filter** (string) - Required - The ID of the filter.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **id** (string) - The unique identifier of the filter.
- **name** (string) - The name of the filter.
- **created** (string) - The timestamp when the filter was created.
- **query_from** (string) - The 'from' query parameter.
- **action_flag** (boolean) - The 'action_flag' parameter.

#### Response Example
```json
{ "success": true, "id": "59759c440e1d676f15e76b5f", "name": "Flag messages from abc", "created": "2017-07-24T07:05:40.355Z", "query_from": "abc", "action_flag": true }
```
```

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

### Get one mailbox

Source: https://github.com/zone-eu/wildduck/wiki/API-Docs

Returns data about a specific mailbox for a given user.

```APIDOC
## GET /users/{user}/mailboxes/{mailbox}

### Description
Returns data about a specific mailbox for a given user.

### Method
GET

### Endpoint
/users/{user}/mailboxes/{mailbox}

### Parameters
#### Path Parameters
- **user** (string) - Required - The ID of the user.
- **mailbox** (string) - Required - The ID of the mailbox.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **id** (string) - The unique identifier for the mailbox.
- **name** (string) - The name of the mailbox.
- **path** (string) - The path of the mailbox.
- **specialUse** (string|null) - Special use attribute for the mailbox.
- **modifyIndex** (integer) - The modification index of the mailbox.
- **subscribed** (boolean) - Indicates if the user is subscribed to the mailbox.
- **total** (integer) - The total number of messages in the mailbox.
- **unseen** (integer) - The number of unseen messages in the mailbox.

### Request Example
```
curl "http://localhost:8080/users/59467f27535f8f0f067ba8e6/mailboxes/597089f1b3378cd394611284"
```

### Response Example
```json
{
    "success": true,
    "id": "597089f1b3378cd394611284",
    "name": "INBOX",
    "path": "INBOX",
    "specialUse": null,
    "modifyIndex": 71,
    "subscribed": true,
    "total": 33,
    "unseen": 8
}
```
```

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

### Import Maildir to WildDuck (Multiple Users)

Source: https://github.com/zone-eu/wildduck/wiki/migration-guide

Imports maildir data for multiple users simultaneously. Consider increasing the 'uploaders' value in the configuration for parallel imports.

```bash
./bin/import-maildir user1@example.com:/var/mail/user1_example.com/ user2@example.com:/var/mail/user2_example.com/ user3@example.com:/var/mail/user3_example.com/
```

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

### Get Archived Message Details

Source: https://github.com/zone-eu/wildduck/wiki/API-Docs

Retrieves the details of a specific archived message.

```APIDOC
## GET /users/{user}/archived/{message}

### Description
Retrieves the details of a specific archived message.

### Method
GET

### Endpoint
/users/{user}/archived/{message}
```

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

### Load and Display Settings

Source: https://github.com/zone-eu/wildduck/blob/master/public/public/config.html

Fetches settings from the server, optionally filtering them, and then populates an HTML table with the retrieved settings. It handles potential errors during the fetch operation and displays them to the user.

```javascript
async function loadSettings(filter) {
  let response;
  try {
    let data = await fetch('/settings' + (filter ? `?filter=${encodeURIComponent(filter)}` : ''), {
      headers: {
        Accept: 'application/json',
        'X-Access-Token': getAccessToken()
      }
    });
    response = await data.json();
  } catch (err) {
    alert(err.message);
    return;
  }
  if (response.error) {
    alert(response.error);
    return;
  }
  let tableElm = document.getElementById('settings-table');
  tableElm.innerHTML = '';
  for (let setting of response.settings) {
    addSettingsRow(tableElm, setting);
  }
}
```

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

### Get message events

Source: https://github.com/zone-eu/wildduck/wiki/API-Docs

Retrieves a history of events related to a specific message.

```APIDOC
## GET /users/{user}/mailboxes/{mailbox}/messages/{message}/events

### Description
Retrieves a history of events related to a specific message.

### Method
GET

### Endpoint
/users/{user}/mailboxes/{mailbox}/messages/{message}/events

### Parameters
#### Path Parameters
- **user** (string) - Required - The username or ID of the user.
- **mailbox** (string) - Required - The name of the mailbox containing the message.
- **message** (string) - Required - The ID of the message.
```

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

### Configure mbsync for Maildir Synchronization

Source: https://github.com/zone-eu/wildduck/wiki/migration-guide

Sets up the mbsync configuration file to synchronize maildir data to WildDuck. This requires IMAP user credentials and specifies connection details, SSL settings, and local/remote paths.

```bash
cat ~/.mbsyncrc
IMAPAccount yourdomain
# Address to connect to
Host 192.168.0.1
User anon@yourdomain.com
Pass gbxiccfdfbqb
# To store the password in an encrypted file use PassCmd instead of Pass
# PassCmd "gpg2 -q --for-your-eyes-only --no-tty -d ~/.mailpass.gpg"
#
# Use SSL
SSLType IMAPS
# The following line should work. If get certificate errors, uncomment the two following lines and read the "Troubleshooting" section.
CertificateFile /pst/19216801.cert
#CertificateFile ~/.cert/imap.gmail.com.pem
#CertificateFile ~/.cert/Equifax_Secure_CA.pem

IMAPStore yourdomain-remote
Account yourdomain

MaildirStore yourdomain-local
Subfolders Verbatim
# The trailing "/" is important
Path /pst/maildir-anon/
Inbox /pst/maildir-anon/Inbox

Channel yourdomain
Master :yourdomain-remote:
Slave :yourdomain-local:
# Exclude everything under the internal [Gmail] folder, except the interesting folders
#Patterns * ![Gmail]* "[Gmail]/Sent Mail" "[Gmail]/Starred" "[Gmail]/All Mail"
# Or include everything
Patterns *
# Automatically create missing mailboxes, both locally and on the server
Create Both
# Save the synchronization state files in the relevant directory
SyncState *
```

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

### Get message attachment

Source: https://github.com/zone-eu/wildduck/wiki/API-Docs

Retrieves the data for a specific attachment associated with an email message.

```APIDOC
## GET /users/{user}/mailboxes/{mailbox}/messages/{message}/attachments/{attachment}

### Description
Returns data about a specific address.

### Method
GET

### Endpoint
/users/{user}/mailboxes/{mailbox}/messages/{message}/attachments/{attachment}

### Parameters
#### Path Parameters
- **user** (string) - Required - The ID of the user
- **mailbox** (string) - Required - The ID of the mailbox
- **message** (string) - Required - The ID of the message
- **attachment** (string) - Required - The ID of the attachment

### Request Example
```
curl "http://localhost:8080/users/59467f27535f8f0f067ba8e6/mailboxes/596c9dd31b201716e764efc2/messages/444/attachments/ATT00001"
```

### Response
#### Success Response (200)
- **Content-Type** (string) - The MIME type of the attachment (e.g., 'image/png').
- **Body** (binary) - The raw content of the attachment.

#### Response Example
```
HTTP/1.1 200 OK
Server: Wild Duck API
Content-Type: image/png
Date: Fri, 21 Jul 2017 18:39:05 GMT
Connection: keep-alive
Transfer-Encoding: chunked

<attachment contents>
```
```

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

### Get message source

Source: https://github.com/zone-eu/wildduck/wiki/API-Docs

Retrieves the raw source content of a specific email message.

```APIDOC
## GET /users/{user}/mailboxes/{mailbox}/messages/{message}/message.eml

### Description
Returns raw message source.

### Method
GET

### Endpoint
/users/{user}/mailboxes/{mailbox}/messages/{message}/message.eml

### Parameters
#### Path Parameters
- **user** (string) - Required - The ID of the user
- **mailbox** (string) - Required - The ID of the mailbox
- **message** (string) - Required - The ID of the message

### Request Example
```
curl "http://localhost:8080/users/59467f27535f8f0f067ba8e6/mailboxes/596c9dd31b201716e764efc2/messages/444/message.eml"
```

### Response
#### Success Response (200)
- **Content-Type** (string) - The MIME type of the message content, typically 'message/rfc822'.
- **Body** (string) - The raw RFC822 formatted message content.

#### Response Example
```
HTTP/1.1 200 OK
Server: Wild Duck API
Content-Type: message/rfc822
Date: Fri, 21 Jul 2017 19:11:04 GMT
Connection: keep-alive
Transfer-Encoding: chunked

Delivered-To: testuser@example.com
Received: .....
<rfc822 formatted message>
```
```

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

### Run WildDuck Docker with Mounted Configuration Volume

Source: https://github.com/zone-eu/wildduck/wiki/Docker

Replace the default configuration directory inside the Docker image by mounting a custom configuration folder from the host.

```bash
docker run -v '/config/from/host:/wildduck/config' nodemailer/wildduck
```

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

### Enable TOTP 2FA

Source: https://github.com/zone-eu/wildduck/wiki/API-Docs

Enables 2FA for an account by verifying the TOTP token generated from the QR code. The 'user' ID and 'token' are required. This call must be made after the setup call.

```bash
curl -XPOST "http://localhost:8080/users/5971da1754cfdc7f0983b2ec/2fa/totp/enable" -H 'content-type: application/json' -d '{
  "token": "455912",
  "ip": "192.168.10.10"
}'
```

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

### Get message events

Source: https://github.com/zone-eu/wildduck/wiki/API-Docs

Retrieves timeline information and events associated with a specific message.

```APIDOC
## GET /users/{user}/mailboxes/{mailbox}/messages/{message}/events

### Description
Returns timeline information about a specific message.

### Method
GET

### Endpoint
/users/{user}/mailboxes/{mailbox}/messages/{message}/events

### Parameters
#### Path Parameters
- **user** (string) - Required - The ID of the user
- **mailbox** (string) - Required - The ID of the mailbox
- **message** (string) - Required - The ID of the message

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful
- **id** (string) - The unique identifier for the event log
- **events** (array) - An array of event objects
  - **id** (string) - Unique identifier for the event
  - **action** (string) - The action performed (e.g., STORE, FORWARD, REJECTED, ACCEPTED)
  - **source** (string) - The source of the event (e.g., MX)
  - **origin** (string) - The origin domain of the event
  - **from** (string) - The sender's email address for this event
  - **to** (array) - An array of recipient email addresses for this event
  - **transtype** (string) - The transaction type (e.g., ESMTPSA)
  - **time** (string) - The timestamp of the event (ISO 8601 format)
  - **seq** (string) - Sequence number for events within a group
  - **src** (string) - Source IP address
  - **dst** (string) - Destination IP address
  - **response** (string) - Server response message for the event

### Request Example
```
curl "http://localhost:8080/users/59cb9b0f8d78173c5fc6871c/mailboxes/59cb9b0f8d78173c5fc6871d/messages/43/events"
```

### Response Example
```json
{
    "success": true,
    "id": "59e9dfac7f60c84cb2c467c4",
    "events": [
        {
            "id": "15f3991b258000f6e5.002",
            "action": "STORE",
            "source": "MX",
            "origin": "sender.com",
            "from": "andris12@example.com",
            "to": ["andris2@example.com"],
            "transtype": "ESMTPSA",
            "time": "2017-10-20T11:36:12.481Z"
        },
        {
            "id": "15f3991b9d7000fb8f",
            "action": "FORWARD",
            "from": "andris12@example.com",
            "to": ["andris@kreata.ee", "andris.reinman@gmail.com"],
            "time": "2017-10-20T11:36:12.523Z"
        },
        {
            "id": "15f3991b9d7000fb8f",
            "seq": "002",
            "action": "REJECTED",
            "src": "0.0.0.0",
            "dst": "gmail-smtp-in.l.google.com",
            "response": "421-4.7.0 This message does not have authentication information or fails to pass authentication checks. To best protect our users from spam, the message has been blocked. Please visit https://",
            "from": "andris12@example.com",
            "to": ["andris.reinman@gmail.com"],
            "time": "2017-10-20T11:36:18.446Z"
        },
        {
            "id": "15f3991b9d7000fb8f",
            "seq": "001",
            "action": "ACCEPTED",
            "src": "0.0.0.0",
            "dst": "aspmx.l.google.com",
            "response": "250 2.0.0 OK 1508499378 v89si365958lje.238 - gsmtp",
            "from": "andris12@example.com",
            "to": ["andris@kreata.ee"],
            "time": "2017-10-20T11:36:18.934Z"
        }
    ]
}
```
```

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

### Run All Tests

Source: https://github.com/zone-eu/wildduck/blob/master/CLAUDE.md

Executes all tests in the project, including database drops and Redis flushes.

```bash
# Run all tests (drops test DB, flushes Redis, then runs tests)
npm test
```

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

### Get one user

Source: https://github.com/zone-eu/wildduck/wiki/API-Docs

Returns data about a specific user identified by their user ID.

```APIDOC
## GET /users/{user}

### Description
Returns data about a specific user identified by their user ID.

### Method
GET

### Endpoint
/users/{user}

### Parameters
#### Path Parameters
- **user** (string) - Required - The ID of the user

### Request Example
```
curl "http://localhost:8080/users/59fc66a03e54454869460e45"
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful
- **id** (string) - The unique identifier for the user
- **username** (string) - The username of the user
- **name** (string) - The name of the user (can be null)
- **address** (string) - The email address of the user
- **retention** (boolean) - Retention policy status
- **enabled2fa** (array) - List of enabled two-factor authentication methods
- **encryptMessages** (boolean) - Whether message encryption is enabled
- **encryptForwarded** (boolean) - Whether forwarding encryption is enabled
- **pubKey** (string) - Public key information
- **keyInfo** (boolean) - Key information status
- **forward** (array) - Forwarding settings
- **targetUrl** (string) - Target URL for forwarding
- **limits** (object) - User limits information
    - **quota** (object) - User quota information
        - **allowed** (number) - Allowed quota in bytes
        - **used** (number) - Used quota in bytes
    - **recipients** (object) - Recipient limits
        - **allowed** (number) - Allowed recipients
        - **used** (number) - Used recipients
        - **ttl** (boolean) - Time-to-live for recipient limits
    - **forwards** (object) - Forwarding limits
        - **allowed** (number) - Allowed forwards
        - **used** (number) - Used forwards
        - **ttl** (boolean) - Time-to-live for forwarding limits
- **tags** (array) - An array of tags associated with the user
- **hasPasswordSet** (boolean) - Indicates if a password is set
- **activated** (boolean) - Indicates if the user account is activated
- **disabled** (boolean) - Indicates if the user account is disabled

#### Response Example
```json
{
    "success": true,
    "id": "59fc66a03e54454869460e45",
    "username": "testuser01",
    "name": null,
    "address": "testuser01@example.com",
    "retention": false,
    "enabled2fa": [],
    "encryptMessages": false,
    "encryptForwarded": false,
    "pubKey": "",
    "keyInfo": false,
    "forward": [],
    "targetUrl": "",
    "limits": {
        "quota": {
            "allowed": 107374182400,
            "used": 289838
        },
        "recipients": {
            "allowed": 2000,
            "used": 0,
            "ttl": false
        },
        "forwards": {
            "allowed": 2000,
            "used": 0,
            "ttl": false
        }
    },
    "tags": ["green", "blue"],
    "hasPasswordSet": true,
    "activated": true,
    "disabled": false
}
```
```
Tokens:
Raw