outbound: add inet_prefer to configure outbound IPv4/IPv6 preference

Author: gramakri

Changes.md

@@ -11,6 +11,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/).
 - feat(rabbitmq_amqplib): configurable message priority #3472
 - add save-sent to Plugins.md
 - deferred hook is now passed the failed recips list and mx info
+- feat(outbound): configurable outbound IPv4/IPv6 preference using `inet_prefer`
 
 ### [3.1.1] - 2025-05-19
 

config/outbound.ini

@@ -19,3 +19,6 @@
 
 ; received_header (default: "Haraka outbound")
 ; received_header=Haraka outbound
+
+; inet_prefer (default: default)
+; inet_prefer=v4

docs/Outbound.md

@@ -53,6 +53,18 @@ Default: false. By default, outbound to a local IP is disabled, to avoid creatin
 
 Set this to specify the delay intervals to use between trying to re-send an email that has a temporary failure condition. The setting is a comma separated list of time spans and multipliers. The time span is a number followed by `s`, `m`, `h`, or `d` to represent seconds, minutes, hours, and days, respectively. The multiplier is an asterisk followed by an integer representing the number of times to repeat the interval. For example, the entry `1m, 5m*2, 1h*3` results in an array of delay times of `[60,300,300,3600,3600,3600]` in seconds. The email will be bounced when the array runs out of intervals (the 7th failure in this case). Set this to `none` to bounce the email on the first temporary failure.
 
+* `inet_prefer`
+
+Default: default. Selects the preferred address family (IP version) to deliver messages.
+
+| Value              | Description |
+|------------------------|-------------|
+| `default` | Prefer IPv6 when IPv4 and IPv6 IPs exist at the same MX priority |
+| `v4`    | Try IPv4 addresses first, then IPv6 |
+| `v6`    | Try IPv6 addresses first, then IPv4 |
+
+Note: Delivery attempts follow MX priority order. Socket-based deliveries ignore this setting.
+
 ### outbound.bounce\_message
 
 See "Bounce Messages" below for details.

outbound/config.js

@@ -17,6 +17,12 @@ function load_config () {
         load_config();
     }).main;
 
+    if (!cfg.inet_prefer) cfg.inet_prefer = 'default';
+    if (!cfg.inet_prefer.match(/^(v4|v6|default)$/)) {
+        logger.warn(exports, `inet_prefer is set to an invalid value: ${cfg.inet_prefer}`);
+        cfg.inet_prefer = 'default';
+    }
+
     // legacy config file support. Remove in Haraka 4.0
     if (!cfg.disabled && config.get('outbound.disabled')) {
         cfg.disabled = true;

outbound/hmail.js

@@ -269,6 +269,21 @@ class HMailItem extends events.EventEmitter {
         // resolves the MX hostnames to IPs
         this.mxlist = await net_utils.resolve_mx_hosts(mxs);
 
+        switch (obc.cfg.inet_prefer) {
+            case 'v4':
+                this.mxlist = [
+                    ...this.mxlist.filter(mx => !net.isIP(mx.exchange) || net.isIPv4(mx.exchange)),
+                    ...this.mxlist.filter(mx => net.isIPv6(mx.exchange))
+                ];
+                break;
+            case 'v6':
+                this.mxlist = [
+                    ...this.mxlist.filter(mx => !net.isIP(mx.exchange) || net.isIPv6(mx.exchange)),
+                    ...this.mxlist.filter(mx => net.isIPv4(mx.exchange))
+                ];
+                break;
+        }
+
         this.try_deliver();
     }