Project setup

1. Copy the source/ directory into your project root, e.g. ./haraka-src/.
2. Set the HARAKA environment variable to your runtime config directory so Haraka resolves plugins and config correctly:

   export HARAKA=/path/to/your/haraka_config
   

3. Create the config directory structure:

   mkdir -p /path/to/your/haraka_config/config
   mkdir -p /path/to/your/haraka_config/plugins
   cp haraka-src/config/*.ini /path/to/your/haraka_config/config/
   

4. Edit /path/to/your/haraka_config/config/smtp.ini to set ports and node count:

   [main]
   nodes=2
   port=25
   listen=0.0.0.0
   

5. Edit config/plugins to list which plugins load at startup (one per line).
6. In your application entry point, require the server module from the source:

   process.env.HARAKA = '/path/to/your/haraka_config'
   const Server = require('./haraka-src/server')
   Server.log_ini = Server.load_smtp_ini()
   Server.setup(Server.start_smtp)
   

7. For TypeScript projects, add a paths alias in tsconfig.json:

   {
     "compilerOptions": {
       "paths": {
         "haraka/*": ["./haraka-src/*"]
       }
     }
   }
   

Public API

Server

// server.js exports an object (not a class)
const Server: {
  config: HarakaConfig,
  plugins: Plugins,
  logger: Logger,
  notes: Record<string, unknown>,
  listeners: any[],
  load_smtp_ini(): void,
  load_http_ini(): void,
  setup(callback: () => void): void,
  start_smtp(): void,
}

Server is the singleton SMTP server. Call Server.load_smtp_ini() then Server.setup(Server.start_smtp) to initialize the cluster and begin accepting connections. Access Server.notes for process-wide shared state across plugins.

Connection (class)

class Connection {
  constructor(client: net.Socket, server: any, smtp_cfg: object)
  local: { ip: string|null, port: number|null, host: string, info: string }
  remote: { ip: string|null, port: number|null, host: string|null }
  transaction: Transaction | null
  results: ResultStore
  notes: Notes
}

Connection represents one live TCP session. Plugins receive a connection instance in every hook call. Read connection.remote.ip for the client address, connection.transaction for the active message envelope, and connection.results to store per-connection plugin results.

outbound (module)

// outbound/index.js named exports
const outbound: {
  temp_fail_queue: Queue,
  delivery_queue: Queue,
  name: 'outbound',
  get_stats(): Stats,
  list_queue(): Promise<QueueItem[]>,
  stat_queue(): Promise<object>,
  flush_queue(domain?: string): Promise<void>,
  ensure_queue_dir(): Promise<void>,
  init_queue(): Promise<void>,
  send_email(...args): void,
}

Use outbound.get_stats() for real-time queue depth metrics, outbound.flush_queue() to retry all deferred messages immediately, and outbound.init_queue() during server startup to prepare the spool directory.

Working examples

Scenario - Starting the SMTP server programmatically

Embed Haraka's server inside an existing Node.js application, listening on a non-privileged port for testing.

// src/mail-server.ts
import path from 'node:path'

process.env.HARAKA = path.resolve(__dirname, '../haraka_config')

// eslint-disable-next-line @typescript-eslint/no-var-requires
const Server = require('../haraka-src/server')

export function startMailServer(): void {
  Server.load_smtp_ini()
  // Override port programmatically before setup
  Server.cfg.main.port = 2525
  Server.cfg.main.nodes = 1
  Server.setup(() => {
    Server.start_smtp()
    Server.logger.loginfo('SMTP server started on port 2525')
  })
}

Scenario - Writing a custom plugin

Register a hook that rejects mail from a blocked sender domain.

// haraka_config/plugins/block_sender.js
'use strict'

exports.register = function () {
  this.register_hook('mail', 'check_sender')
}

exports.check_sender = function (next, connection, params) {
  const txn = connection.transaction
  const mail_from = params[0] // Address object
  const blocked = ['spam.example.com']

  if (blocked.includes(mail_from.host)) {
    txn.results.add(this, { fail: 'blocked_sender' })
    return next(DENY, 'Sender domain is not accepted')
  }

  txn.results.add(this, { pass: 'sender_ok' })
  return next()
}

Add block_sender to haraka_config/config/plugins to activate it.

Scenario - Querying outbound queue stats

Expose queue metrics via an Express endpoint alongside the running Haraka server.

// src/queue-api.ts
import express from 'express'
import path from 'node:path'

process.env.HARAKA = path.resolve(__dirname, '../haraka_config')
const outbound = require('../haraka-src/outbound')

const app = express()

app.get('/queue/stats', async (_req, res) => {
  try {
    await outbound.init_queue()
    const stats = outbound.get_stats()
    const items = await outbound.list_queue()
    res.json({ stats, queued: items.length })
  } catch (err) {
    res.status(500).json({ error: (err as Error).message })
  }
})

app.post('/queue/flush', async (_req, res) => {
  await outbound.flush_queue()
  res.json({ flushed: true })
})

app.listen(3001)

File walkthrough

• server.js - Initializes cluster workers, loads TLS config, binds TCP endpoints, and dispatches to connection.js for each accepted socket.
• connection.js - Full SMTP command parser and state machine; emits plugin hooks at each protocol stage (connect, helo, mail, rcpt, data, quit).
• transaction.js - Stores the envelope (MAIL FROM / RCPT TO), message headers, and body stream for a single delivery attempt.
• plugins.js - Scans plugin paths, require()s each plugin file, registers hook callbacks, and calls them in order with a next() continuation.
• logger.js - Provides logdebug/loginfo/logwarn/logerr at the module level; add_log_methods injects these onto any object (Server, Plugin instances).
• tls_socket.js - Wraps net.Socket in a pluggableStream that can upgrade to TLS mid-connection; handles SNI certificate lookup via certsByHost.
• outbound/index.js - Entry point for the delivery subsystem; re-exports queue functions from queue.js and HMailItem delivery logic.
• outbound/ - Contains hmail.js (per-message delivery state), todo.js (queue item schema), qfile.js (spool file format), config.js, and fsync_writestream.js.
• smtp_client.js - Async SMTP client used by outbound to connect to destination MX hosts and relay messages.
• host_pool.js - Manages a round-robin or weighted pool of relay hosts for forwarding scenarios.
• rfc1869.js - Parses ESMTP extension parameters from EHLO responses.
• endpoint.js - Abstracts a single listen address (host:port or UNIX path) and its associated server instance.
• line_socket.js - Buffers raw socket data into CRLF-delimited lines for SMTP command parsing.
• haraka.js - CLI interface; handles -i (init), -c (run), -h (help) flags.
• config/ - Default INI files consumed by haraka-config; copy to your config dir and override.
• plugins/ - Bundled plugins: auth backends, queue handlers, SMTP bridge, forward, proxy.
• docs/ - Reference documentation for the plugin API, transaction object, and configuration keys.

Common pitfalls and fixes

• HARAKA env var not set: Haraka resolves config and plugin paths relative to process.env.HARAKA; if unset it falls back to cwd, causing "config not found" errors. Fix: always export HARAKA=/your/config/dir before requiring server.js.
• Port 25 requires root: Binding to ports below 1024 fails without elevated privileges. Fix: run under sudo, use authbind, or set port=2525 in smtp.ini for development.
• node-gyp build failures: Some dependencies compile native addons. Fix: install build-essential (Linux) or Xcode CLI tools (macOS) and ensure python3 is on PATH.
• CJS-only modules in ESM projects: Haraka uses require() throughout. Fix: import via createRequire or set "type": "commonjs" in your wrapper package.json.
• Plugin hook not firing: Hook name must exactly match the protocol stage string (e.g. 'mail' not 'mail_from'). Fix: cross-reference docs/Plugins.md for the canonical hook list.
• Queue directory permissions: outbound writes spool files to queue/ inside the config dir; the process user must own that directory. Fix: mkdir -p $HARAKA/queue && chown $USER $HARAKA/queue.

Vibe-coding prompt template

I have dropped the Haraka Node.js mail server source into `./haraka-src/` 
and placed USAGE.md at the project root. The upstream package is `user@example.com`.

Please help me integrate Haraka into my existing Node.js/Express project step by step:

1. Read USAGE.md and the file excerpts for server.js, connection.js, plugins.js, 
   and outbound/index.js to understand the real exported API.
2. Set up the HARAKA environment variable and config directory structure as described 
   in USAGE.md § "Project setup".
3. Add a `startMailServer()` function that programmatically starts the SMTP server 
   on port 2525 without forking cluster workers (nodes=1).
4. Create a custom plugin in haraka_config/plugins/ that logs every accepted sender 
   address using the connection.results API.
5. Add an Express route GET /mail/queue that calls outbound.get_stats() and returns 
   the result as JSON.
6. Wire everything so the Express HTTP server and the Haraka SMTP server start 
   together from a single `npm start` command.
7. Point out any pitfalls from USAGE.md § "Common pitfalls and fixes" that apply 
   to my setup and suggest fixes.

Only use symbols and imports that are visible in the file excerpts in USAGE.md. 
Do not invent plugin hooks or API methods.

License and credit

Haraka is released under the MIT License - see source/LICENSE for the full text. The project was started by Matt Sergeant and is maintained by the Haraka community. Upstream repository and package: Haraka on npm / github.com/haraka/Haraka.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.