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 three files to separate concerns:

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.

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:

# RHEL / Fedora
dnf install -y python3-boto3

# Debian / Ubuntu
apt install -y python3-boto3

2. Create the secrets file

The secrets file stores your API credentials in a secure location with strict permissions. Both RHEL and Debian families use /etc/postfix/ for Postfix configuration files. The field names are generic — comments above each value indicate what each means for your specific provider.

Microsoft Graph API

cat > /etc/postfix/api-secrets.json <<'EOF'
{
    "API_PROVIDER": "graph",

    "_comment_tenant": "Microsoft Entra (Azure AD) Tenant ID",
    "API_TENANT_OR_REGION": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",

    "_comment_id": "App Registration Client ID",
    "API_ID": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",

    "_comment_secret": "App Registration Client Secret",
    "API_SECRET": "your-client-secret-here",

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

Amazon SES

cat > /etc/postfix/api-secrets.json <<'EOF'
{
    "API_PROVIDER": "ses",

    "_comment_region": "AWS Region for SES (e.g. us-east-1)",
    "API_TENANT_OR_REGION": "us-east-1",

    "_comment_id": "IAM Access Key ID",
    "API_ID": "AKIAIOSFODNN7EXAMPLE",

    "_comment_secret": "IAM Secret Access Key",
    "API_SECRET": "your-secret-key-here",

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

Lock down permissions

chown root:root /etc/postfix/api-secrets.json
chmod 600 /etc/postfix/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.

mkdir -p /opt/postfix-relay

cat > /opt/postfix-relay/relay-config.json <<'EOF'
{
    "ADMIN_NOTIFICATION_EMAIL": "admin@yourdomain.com",

    "NOTIFY_ON_OVERRIDE": true,

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

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

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

4. Install the relay script

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

wget -O /opt/postfix-relay/postfix-api-relay https://meikakuconsulting.com/guides/postfix-relay/postfix-api-relay
chmod 755 /opt/postfix-relay/postfix-api-relay
chown root:root /opt/postfix-relay/postfix-api-relay

Verify the script compiles

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.

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
postconf -e "mynetworks = 127.0.0.0/8, 192.168.1.0/24"

# Route ALL outbound mail through our API relay transport
postconf -e "default_transport = apirelay"

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

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 and recipient as arguments:

cat >> /etc/postfix/master.cf <<'EOF'

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

Restart Postfix

systemctl restart postfix

6. Test

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

echo "Test message from the API relay" | sendmail -f alerts@yourdomain.com admin@yourdomain.com

Check the Postfix mail log for confirmation:

# RHEL / Fedora
journalctl -u postfix -n 50 --no-pager

# Debian / Ubuntu
tail -50 /var/log/mail.log

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@yourdomain.com admin@yourdomain.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@yourdomain.com

The email should arrive at your admin address with the subject prefixed by [Sent by unknown-device@local]. If NOTIFY_ON_OVERRIDE is enabled, a separate notification email will also be delivered to the admin.

7. 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:

8. Error handling and logging

The relay script includes robust error handling to ensure you are aware of delivery problems:

The log file location is configured in relay-config.json. The default is /opt/postfix-relay/postfix-api-relay.log. Check it if you suspect delivery issues.

Troubleshooting