Docs Get key
All guides
Bulk email

Haraka for bulk email: programmable SMTP transport

Decide when Haraka fits bulk sending, configure authenticated submission and outbound queue plugins, and keep campaign state upstream.

Reviewed

Haraka is a Node.js SMTP server with JavaScript hooks at connection, recipient, data, and queue stages. Choose it when you need application-specific SMTP behavior in plugins: custom recipient policy, message inspection, or a handoff that a standard MTA does not express cleanly. It is not a campaign manager, a mailbox store, or an IMAP service.

This guide covers the bulk-sending decision and the queue boundary. Installing Haraka, configuring recipient policy, and operating submission have dedicated Haraka server guides.

Prerequisites

  • A maintained Node.js release and npm.
  • A dedicated service directory and a supported privilege model for binding SMTP ports.
  • TLS certificates for public submission and, if receiving, MX.
  • A durable queue or downstream store that matches your acceptance contract.
  • DNS you control, including PTR, SPF, DKIM, and DMARC for outbound domains.

Haraka is MIT-licensed. The official getting-started guide documents installation, the service directory, domains, and plugins for the current release.

Create an isolated configuration

Install the package and create a service directory rather than editing a system-wide default:

haraka -i /path/to/haraka-test

The command creates configuration, plugin, and queue files. Review them before starting a listener. Set the SMTP hostname, accepted domains, TLS material, and plugin order deliberately. A fresh configuration is a starting point, not a production policy.

Two paths are commonly confused:

  • Local-domain reception often uses smtp-forward to hand mail to another service.
  • Authorized relay puts messages marked for relaying into Haraka’s outbound queue.

Adding a domain to a host list does not create a mailbox, a durable webhook receiver, or an outbound relay permission. Choose the path that matches the job and test the other path is denied.

Use Haraka as outbound transport

For bulk application mail, the application submits authenticated messages and Haraka queues them for outbound delivery. Configure the documented authentication plugin, a restricted submission listener, TLS, sender/relay authorization, and the signing plugin with protected DKIM keys.

Authentication success must not become permission to impersonate every hosted sender. Map authenticated applications or tenants to allowed From domains and envelopes. A shared submission credential with unrestricted sender choice is a relay abuse incident waiting to happen.

For each bulk job:

  1. Persist the intended send and a stable identity before submission.
  2. Submit with bounded concurrency; queue depth is not a rate limit.
  3. Record the queue identity returned by the submission path.
  4. Inspect delivery, deferral, and bounce evidence before resending.

Haraka has an outbound delivery engine, but the queue is only as durable as the configured plugin and storage. Do not acknowledge work to your own application before it is durably accepted.

Design the downstream handoff

If a plugin calls an HTTP service or parser, do not do slow work inside the SMTP transaction. Either persist the raw message and envelope metadata, or require a successful durable downstream acceptance before returning SMTP success. Define temporary failure, permanent rejection, timeout, and duplicate processing explicitly.

Never return success because a network request was started. The durable handoff guide covers this boundary in detail. Protect raw content, impose size limits, and keep credentials out of logs.

Operate submission and recovery

Monitor queue age, delivery failures, disk capacity, plugin errors, and TLS expiry. Test invalid credentials, unauthenticated relay, an accepted recipient, an unknown recipient, and an unavailable downstream service. A healthy process is not proof that any of those policies work.

Do not delete the queue or resubmit application messages merely because delivery is delayed. An uncertain connection can hide a successful acceptance; reconcile existing evidence first. Keep configuration, keys, and queue recovery in the backup plan. The submission queue guide goes further.

Haraka does not provide a mail store or IMAP. Replies and mailbox access need another component. Campaign state, unsubscribe handling, and audience segmentation stay upstream.

Where MailKite fits

MailKite, which we build, is a hosted sending and receiving API. It replaces managed delivery operations, not a programmable SMTP edge. It supports broadcasts and personalized batches but prohibits unsolicited bulk or commercial mail, sending without consent, and sending after opt-out.

If you use Haraka for inbound policy and MailKite for application mail, keep the two authentication and identity models separate. A MailKite API key is not a Haraka submission credential, and a Haraka plugin success does not carry a MailKite signature. See MailKite sending and receiving.

Next steps

Sources reviewed 2026-11-07: Haraka getting started, Haraka repository, license, and the open-source bulk email comparison.