Centralized Postfix API Mail Relay

Why a centralized relay?

Our previous guides — Proxmox Email via Graph/SES and DNF5 Automatic Email via Graph/SES — show how to configure individual servers to send notifications directly through a cloud API. That works well when you only have a few systems to manage.

But on a site with dozens of servers, switches, UPS devices, storage appliances, and other infrastructure — each needing to send alerts — manually deploying and maintaining API credentials on every system becomes impractical. Credentials expire, and you would need to rotate them everywhere.

The solution is a centralized API relay. Stand up a single dedicated VM or container running Postfix. Point every internal system at it using standard SMTP (the default for nearly every appliance and daemon). This relay accepts unauthenticated mail from your LAN, then delivers it to the outside world exclusively through secure HTTPS API calls — never over traditional SMTP ports that may be blocked by your ISP or firewall.

Internal systems (standard SMTP)
  → Centralized Postfix relay (your LAN)
  → Python script (this guide)
  → Microsoft Graph API  or  Amazon SES  (HTTPS, port 443)
  → Recipient mailbox

Architecture overview

The relay uses four files, all kept together in /opt/postfix-relay/:

This separation means routing changes (adding an approved sender, changing the admin address) do not require touching the secrets file, and credential rotation does not require editing the configuration.

1. Prerequisites

This guide assumes you have a Linux system (RHEL/Fedora, Debian/Ubuntu, or similar) with Postfix installed at its default settings. Most minimal server installations include Postfix, or it can be installed with your package manager. All commands assume you are logged in as a non-root user with sudo access.

You also need credentials for your chosen cloud provider. If you have not set those up yet, see our Microsoft Graph App Registration guide.

Install Python dependencies

The Graph API provider uses only Python 3 standard library modules — no additional packages are needed. The SES provider requires boto3. On RHEL/Fedora, also install SELinux policy tools for managing the relay's security context:

# RHEL / Fedora
sudo dnf install -y python3-boto3 policycoreutils-python-utils

# Debian / Ubuntu
sudo apt install -y python3-boto3

2. Create the service account and secrets file

Postfix's pipe daemon refuses to execute commands as root, so a dedicated service account is required. All relay files — the script, config, secrets, and logs — live together in /opt/postfix-relay/ owned by this account.

sudo useradd -r -s /usr/sbin/nologin -d /opt/postfix-relay postfix-relay
sudo mkdir -p /opt/postfix-relay
sudo chown postfix-relay:postfix-relay /opt/postfix-relay

The secrets file stores your API credentials. The field names are generic so the same structure works for either provider — dual comments above each value indicate what it means for Graph vs. SES. Set API_PROVIDER to graph or ses, then fill in the remaining fields for your chosen provider:

sudo tee /opt/postfix-relay/api-secrets.json > /dev/null <<'EOF'
{
    "API_PROVIDER": "graph",

    "_comment_graph": "Microsoft Entra (Azure AD) Tenant ID",
    "_comment_ses": "AWS Region for SES (e.g. us-east-1)",
    "API_TENANT_OR_REGION": "YOUR_TENANT_ID_OR_REGION",

    "_comment_id_graph": "App Registration Client ID",
    "_comment_id_ses": "IAM Access Key ID",
    "API_ID": "YOUR_CLIENT_OR_ACCESS_KEY_ID",

    "_comment_secret_graph": "App Registration Client Secret",
    "_comment_secret_ses": "IAM Secret Access Key",
    "API_SECRET": "YOUR_SECRET",

    "_comment_expires": "Expiration date of the secret or access key (YYYY-MM-DD)",
    "API_EXPIRATION_DATE": "2028-04-05"
}
EOF

Lock down permissions

sudo chown postfix-relay:postfix-relay /opt/postfix-relay/api-secrets.json
sudo chmod 600 /opt/postfix-relay/api-secrets.json

The script enforces 0600 permissions and will refuse to run if the secrets file is accessible to group or world.

3. Create the configuration file

The configuration file controls routing behavior — which sender addresses are approved, who receives admin alerts, and where to log errors. This file does not contain secrets and is safe to manage openly.

sudo tee /opt/postfix-relay/relay-config.json > /dev/null <<'EOF'
{
    "ADMIN_NOTIFICATION_EMAIL": "admin@domain.com",

    "NOTIFY_ON_OVERRIDE": true,

    "_comment_silent": "Senders that are always rewritten but never trigger an admin notification",
    "SILENT_OVERRIDE_ADDRESSES": [
        "device@domain.com"
    ],

    "LOG_FILE_PATH": "/opt/postfix-relay/postfix-api-relay.log",

    "RATE_LIMIT_PER_MINUTE": 28,

    "VALID_FROM_ADDRESSES": [
        "alerts@domain.com",
        "network@domain.com"
    ],

    "_comment_trusted": "IPs and domains work together: a device must match both an IP and a domain to relay",
    "TRUSTED_DEVICE_IPS": [
        "10.1.1.X"
    ],

    "TRUSTED_DEVICE_DOMAINS": [
        "domain.com"
    ],

    "DEFAULT_FROM_ADDRESS": "alerts@domain.com"
}
EOF

4. Install the relay script

Download the postfix-api-relay Python script into /opt/postfix-relay/:

sudo curl -fsSL -o /opt/postfix-relay/postfix-api-relay https://meikakuconsulting.com/guides/postfix-relay/postfix-api-relay
sudo chmod 755 /opt/postfix-relay/postfix-api-relay
sudo chown postfix-relay:postfix-relay /opt/postfix-relay/postfix-api-relay

# Pre-create the log file with correct ownership
sudo touch /opt/postfix-relay/postfix-api-relay.log
sudo chown postfix-relay:postfix-relay /opt/postfix-relay/postfix-api-relay.log

Verify the script compiles

sudo python3 -m py_compile /opt/postfix-relay/postfix-api-relay

If this command produces no output, the script is syntactically valid.

5. Configure Postfix

Two Postfix files need to be modified: main.cf (general settings) and master.cf (service definitions). These changes tell Postfix to accept mail from your LAN and route all outbound mail through the relay script instead of trying to deliver via traditional SMTP.

sudo cp /etc/postfix/main.cf /etc/postfix/main.cf.bak.$(date +%Y%m%d)

main.cf — Accept LAN traffic and set the default transport

Replace 192.168.1.0/24 with your actual internal network CIDR. You can list multiple networks separated by commas.

# Allow your internal network to relay through this server
sudo postconf -e "mynetworks = 127.0.0.0/8, 192.168.1.0/24"

# Route ALL outbound mail through our API relay transport.
# The ":api-relay" suffix is a literal next-hop sentinel (NOT a
# hostname) that forces every recipient — regardless of domain — to
# share the same delivery next-hop, so Postfix bundles them together.
sudo postconf -e "default_transport = apirelay:api-relay"

# Bind Postfix to all interfaces so LAN clients can connect
sudo postconf -e "inet_interfaces = all"

# Bundle ALL recipients into a single pipe invocation (critical for CC/BCC)
sudo postconf -e "apirelay_destination_recipient_limit = 0"

main.cf — Tune retry backoff timing

Three Postfix parameters control how quickly deferred messages are retried:

• queue_run_delay — how often the queue manager wakes up to scan for messages that are eligible to retry (default 300 s).
• minimal_backoff_time — minimum time a message must wait before it becomes eligible for its first retry (default 300 s).
• maximal_backoff_time — ceiling on the exponential backoff applied to messages that have been deferred multiple times (default 4000 s — over an hour).

All three must be tuned together. Setting the backoff times alone only makes messages eligible to retry sooner — if queue_run_delay is still at its 300 s default, Postfix will not actually attempt them until the next scan, which can be nearly five minutes away.

There is also a subtle race to avoid: if minimal_backoff_time is set equal to or close to queue_run_delay, the queue runner can fire a few seconds before deferred messages become eligible. It finds nothing ready, skips them, and the messages must wait a full extra cycle — producing delays nearly double what you configured. Set the backoff times comfortably below queue_run_delay so deferred messages are always ready before the next scan:

sudo postconf -e "queue_run_delay = 62s"
sudo postconf -e "minimal_backoff_time = 30s"
sudo postconf -e "maximal_backoff_time = 30s"

master.cf — Define the API relay transport

Add the following line to the end of /etc/postfix/master.cf. This defines a Postfix service named apirelay that pipes every message through the Python script, passing the envelope sender, all recipients, and the client IP as arguments:

sudo tee -a /etc/postfix/master.cf > /dev/null <<'EOF'

# API mail relay transport — routes outbound mail through Graph or SES API
apirelay  unix  -       n       n       -       1       pipe
  flags=Rq user=postfix-relay argv=/opt/postfix-relay/postfix-api-relay ${sender} ${queue_id} ${recipient} ${client_address}
EOF

Restart Postfix

sudo systemctl restart postfix

SELinux policy (Fedora / RHEL)

On systems with SELinux enforcing, the Postfix pipe daemon runs in a confined domain (postfix_pipe_t) that requires explicit permission to create and write files in /opt/postfix-relay/. Without the correct policy, the relay script fails with PermissionError(13, 'Permission denied')when writing the rate-limit state or log files.

Install the complete policy using the pre-built type enforcement file below, which includes all required permissions: write on directories and files, open and read for state file access, and the process inheritance permissions (noatsecure, rlimitinh, siginh) that Postfix master requires when spawning pipe, smtpd, and cleanup worker processes.

# Create a permanent home for the policy source
sudo mkdir -p /opt/postfix-relay/selinux

# Write the complete type enforcement policy
sudo tee /opt/postfix-relay/selinux/postfix-relay.te > /dev/null << 'EOF'
module postfix-relay 1.2;

require {
    type postfix_master_t;
    type postfix_spool_t;
    type postfix_pipe_t;
    type postfix_cleanup_t;
    type postfix_pickup_t;
    type postfix_smtpd_t;
    type logrotate_t;
    class dir  { add_name remove_name write };
    class file { create unlink write open read getattr rename };
    class process { noatsecure rlimitinh siginh };
}

# Allow Postfix master to spawn worker processes with full inheritance
allow postfix_master_t postfix_cleanup_t:process { noatsecure rlimitinh siginh };
allow postfix_master_t postfix_pickup_t:process  { noatsecure rlimitinh siginh };
allow postfix_master_t postfix_pipe_t:process    { noatsecure rlimitinh siginh };
allow postfix_master_t postfix_smtpd_t:process   { noatsecure rlimitinh siginh };

# Allow the relay script to create and update its runtime files
# (the rate-limit state file and the activity log)
allow postfix_pipe_t postfix_spool_t:dir  { add_name remove_name write };
allow postfix_pipe_t postfix_spool_t:file { create unlink write open read getattr };

# Allow logrotate to rotate the relay log file
# (rename the old file, create the new one, compress older rotations)
allow logrotate_t postfix_spool_t:file { getattr open read rename unlink create write };
allow logrotate_t postfix_spool_t:dir  { add_name remove_name write };
EOF

# Build and install the module
cd /opt/postfix-relay/selinux
sudo checkmodule -M -m -o postfix-relay.mod postfix-relay.te
sudo semodule_package -o postfix-relay.pp -m postfix-relay.mod
sudo semodule -i postfix-relay.pp
sudo semodule -B
sudo chown -R postfix-relay:postfix-relay /opt/postfix-relay/selinux

Set permanent file context labels

The SELinux policy grants postfix_pipe_t write access to files labeled postfix_spool_t, and relies on the relay script being executable as bin_t. By default, /opt/postfix-relay/ inherits usr_t from /opt/. Without explicit file context rules, any future restorecon — triggered automatically by SELinux package upgrades — will reset the labels and break the relay. Register the correct contexts permanently:

# Label the directory and all state/log files as postfix_spool_t
sudo semanage fcontext -a -t postfix_spool_t "/opt/postfix-relay(/.*)?"

# Override the script itself to bin_t so Postfix pipe can execute it
sudo semanage fcontext -a -t bin_t "/opt/postfix-relay/postfix-api-relay"

# Apply the labels
sudo restorecon -Rv /opt/postfix-relay/

The two rules work together: the first labels everything under /opt/postfix-relay/ as postfix_spool_t (matching what the policy allows the pipe daemon to write), and the second overrides just the script back to bin_t so the pipe daemon can execute it. More-specific rules take precedence over less-specific ones, so the script override wins.

Debian and Ubuntu do not use SELinux by default — this step applies only to Fedora, RHEL, AlmaLinux, Rocky Linux, and similar distributions. Proceed to step 6 to confirm delivery works correctly in enforcing mode.

6. Rate limiting

Microsoft 365 enforces a rate limit of 30 messages per minute per mailbox via the Graph API. On a busy network where dozens of systems may generate alerts simultaneously, it is easy to exceed this limit.

The relay script includes a sliding-window rate limiter that enforces this cap automatically. Here is how it works:

The default limit is 28 per minute — two below the Microsoft cap — to leave headroom for override notifications and credential expiry alerts that the script sends in addition to the primary message. You can adjust or disable this in /opt/postfix-relay/relay-config.json:

// Set to 0 to disable rate limiting entirely
"RATE_LIMIT_PER_MINUTE": 28

7. Test

Send a test email through the relay from the local system:

sendmail -f alerts@domain.com admin@domain.com << 'EOF'
Subject: [RELAY TEST] Basic Test
To: admin@domain.com

Test message from the API relay.
EOF

Check the relay log for confirmation:

tail -20 /opt/postfix-relay/postfix-api-relay.log

Test CC and BCC delivery

This is the most important functional test. It verifies that Postfix delivers all envelope recipients in a single pipe invocation and that the script correctly classifies them as To, CC, or BCC based on the MIME headers.

Replace to@external.com with an address you control and bcc@domain.com with an internal address. Use sendmail (not swaks or similar tools) — it goes through the real Postfix pipeline and exercises the correct SELinux domain transitions.

sendmail -f alerts@domain.com to@external.com bcc@domain.com << 'EOF'
From: alerts@domain.com
To: to@external.com
Subject: [RELAY TEST] BCC Classification
MIME-Version: 1.0
Content-Type: text/plain

BCC classification test — safe to delete.
EOF

Both addresses are in the SMTP envelope, but only to@external.com appears in the MIME To: header. The relay classifies bcc@domain.com as BCC because it is absent from all MIME headers. Check the relay log:

tail -10 /opt/postfix-relay/postfix-api-relay.log

A successful delivery shows a single PROCESSING line with both recipients, followed by CLASSIFIED and DELIVERED:

[...] PROCESSING: sender='alerts@domain.com' recipients=['to@external.com', 'bcc@domain.com'] client_ip=''
[...] CLASSIFIED: to=['to@external.com'] cc=[] bcc=['bcc@domain.com'] (mime_to=['to@external.com'] mime_cc=[])
[...] DELIVERED: from='alerts@domain.com' to=['to@external.com'] cc=[] bcc=['bcc@domain.com'] subject='[RELAY TEST] BCC Classification'

If you see separate PROCESSING entries for each recipient (one per domain), the apirelay_destination_recipient_limit = 0 setting is missing from main.cf — see the troubleshooting section below.

Test from another system on your LAN

From any other server or appliance on your network, configure it to send SMTP mail to the relay system's IP address on port 25. For a quick test from another Linux box:

echo "Test from a remote system" | sendmail -S relay-hostname:25 -f alerts@domain.com admin@domain.com

Test sender override

Send from an address that is not in your VALID_FROM_ADDRESSES list to verify the override logic:

echo "This should trigger an override" | sendmail -f unknown-device@local admin@domain.com

The email should arrive at your admin address sent from the default address instead of the unknown sender. If NOTIFY_ON_OVERRIDE is enabled, a separate notification email will also be delivered to the admin identifying the original sender.

8. Point your internal systems at the relay

On each server, switch, UPS, or appliance, configure SMTP to point at this relay. The exact setting varies by device, but the values are always:

9. Error handling and logging

The relay script classifies every API failure as either transient or permanent and tells Postfix how to handle it:

In all failure cases, the API error response (including HTTP status code and body) is written to two locations:

The -f flag means “follow” — the command will print the last several lines and then stay open, displaying new entries as they appear in real time. Press Ctrl+C to stop.

10. Log rotation

The relay log file will grow indefinitely if left unmanaged. Most Linux distributions ship with logrotate installed by default — add a configuration file to rotate the relay log automatically:

sudo tee /etc/logrotate.d/postfix-api-relay > /dev/null <<'EOF'
/opt/postfix-relay/postfix-api-relay.log {
    weekly
    rotate 4
    compress
    delaycompress
    missingok
    notifempty
    create 0644 postfix-relay postfix-relay
    su postfix-relay postfix-relay
    nodateext
}
EOF

Verify the configuration parses correctly with a dry run:

sudo logrotate -d /etc/logrotate.d/postfix-api-relay

The -d flag is debug mode — it shows what logrotate would do without actually rotating anything.

Troubleshooting