Haraka SMTP Server

Common errors

• Error: listen EACCES: permission denied 0.0.0.0:25

  cause Haraka is attempting to listen on a privileged port (like 25) without sufficient user permissions (e.g., not run as root).
  fix Run Haraka with `sudo`: `sudo haraka -c /path/to/haraka_instance`.

• Error: listen EADDRINUSE: address already in use :::25

  cause Another process (e.g., Postfix, Sendmail, another Haraka instance) is already listening on the configured SMTP port.
  fix Stop the conflicting process, or configure Haraka to listen on a different port by editing `config/smtp.ini`'s `listen` setting.

• Error: Cannot find module 'Haraka' or Error: Cannot find module 'haraka'

  cause The `haraka` package is not installed or not discoverable in the current Node.js environment/path.
  fix If installed globally, ensure your `PATH` includes npm's global bin directory. If installing locally for development, ensure you run `npm install` in the project root. For CLI usage, `npm install -g Haraka` is usually sufficient.

• 550 5.7.1 Relaying denied (or similar 'Mailbox unavailable' error for valid recipient)

  cause Haraka is configured to accept mail only for domains listed in `config/host_list`, and the recipient's domain is not present in that file.
  fix Add the recipient's domain (e.g., `example.com`) to the `config/host_list` file in your Haraka instance directory and restart Haraka.

Warnings

• breaking Haraka v3.1.0 introduced a significant breaking change by consolidating several disparate configuration files (e.g., `haproxy_hosts`, `smtpgreeting`, `databytes`) into a single `connection.ini` file. Existing installations on older versions will need to migrate their settings.
  Fix: Review your existing configuration files (e.g., `haproxy_hosts`, `smtpgreeting.ini`, `databytes.ini`) and migrate their settings to the appropriate sections within `config/connection.ini`. Refer to the `connection.ini` documentation for the new structure.
• breaking As of Haraka v3.1.2, the minimum required Node.js version is 20 or higher. Running Haraka on older Node.js versions (e.g., Node.js 18) will result in errors.
  Fix: Upgrade your Node.js environment to version 20 or newer. It is recommended to use an LTS (Long Term Support) release of Node.js.
• deprecated The `graph` plugin was removed in Haraka v3.1.3 due to its dependency on the unmaintained `sqlite3` library. If you relied on this plugin for metrics or visualization, it is no longer available.
  Fix: Remove `graph` from your `config/plugins` file. Explore alternative monitoring and logging solutions that integrate with Haraka's standard logging (e.g., by piping logs to external analysis tools).
• gotcha To bind to privileged ports (e.g., standard SMTP port 25), Haraka must be run with root privileges. Starting Haraka without sufficient permissions will result in `EACCES` errors.
  Fix: Always use `sudo haraka -c /path/to/instance` when running Haraka on ports below 1024. Alternatively, configure Haraka to listen on a non-privileged port (e.g., 2525) for testing, or use capabilities/setuid wrappers in production if direct root is undesired.
• gotcha Haraka will only accept mail for domains explicitly listed in `config/host_list`. If mail for a domain is rejected or not routed correctly, it's often due to the domain missing from this file.
  Fix: Ensure that all domains for which Haraka should accept or process mail are listed one per line in the `config/host_list` file within your Haraka instance directory. Restart Haraka after making changes to configuration files.

Install

• npm install Haraka npm
• yarn add Haraka yarn
• pnpm add Haraka pnpm

Imports

• Haraka CLI Execution
  wrong:

  import Haraka from 'Haraka'

  correct:

  haraka -c /path/to/haraka_instance

  Haraka is primarily a command-line application. While the main script (`haraka.js`) can be required, it's not designed to export a programmatic API for embedding. Its typical use is via the `haraka` CLI command.
• Plugin System Integration
  wrong:

  import { hook_data } from 'Haraka/plugin_api'

  correct:

  // Within a Haraka plugin file (e.g., my_plugin.js):
  // module.exports.hook_data = function (next, connection, transaction) { ... };

  Plugins are loaded by Haraka and interact through predefined hook functions (e.g., `hook_data`, `hook_rcpt_to`). Core objects like `connection` and `transaction` are passed as arguments to these hooks, not imported directly.
• Configuration Access (Internal)
  wrong:

  import { config } from 'Haraka';

  correct:

  const config = require('Haraka/config');

  For advanced plugin development or internal scripting, Haraka's configuration system can be accessed directly using CommonJS `require` paths relative to the Haraka installation. This is not a public API but is a common pattern for internal modules and power users.

Quickstart

Demonstrates the typical workflow for installing Haraka globally, initializing a new server instance, and preparing it for startup as an SMTP server, including notes on configuration and permissions.

#!/usr/bin/env node

// 1. Install Haraka globally (recommended for CLI usage)
// npm install -g Haraka

// 2. Create a directory for your Haraka instance and initialize it
const { execSync } = require('child_process');
const path = require('path');
const fs = require('fs');

const instancePath = path.join(__dirname, 'haraka_test_instance');

console.log(`Initializing Haraka instance at ${instancePath}...`);
execSync(`haraka -i ${instancePath}`, { stdio: 'inherit' });

// 3. (Optional) Configure accepted domains (e.g., 'example.com')
//    Edit config/host_list within haraka_test_instance to add your domain.
//    For example: echo 'example.com' > ${instancePath}/config/host_list

// 4. (Optional) Configure outbound forwarding (smtp_forward plugin is default)
//    Edit config/smtp_forward.ini to specify destination SMTP server.
//    Example: echo '[main]\nforward_to=localhost:25000' > ${instancePath}/config/smtp_forward.ini

// 5. Start Haraka (requires root permissions for ports below 1024, like 25)
console.log(`Starting Haraka server (may require sudo for port 25)...`);
console.log(`To stop, use Ctrl+C or kill the process.`);
// In a real scenario, you'd run this from your terminal with 'sudo haraka -c haraka_test_instance'
// For demonstration, we'll just log the command.
console.log(`
Run this command in your terminal: sudo haraka -c ${instancePath}`);

// Example of waiting and then showing how to potentially stop for a script
// In a real application, you'd use a process manager like PM2.
// setTimeout(() => {
//   console.log('Demonstration complete. Exiting.');
//   // In a real script, you'd send a signal to stop the process.
// }, 15000);