Initial project setup: hMailServer SMTP relay configuration issue and resolution

2026-04-04 22:03:53 -04:00
commit 56c7b572c3
2 changed files with 198 additions and 0 deletions
@@ -0,0 +1,101 @@
+# hMailServer Configuration Reference
+
+## SMTP Relay Setup
+
+### Mailjet Relay Credentials
+```
+SMTP Server: smtp-relay.mailjet.com
+Port: 587 (STARTTLS)
+Connection Security: STARTTLS
+Authentication: Required
+Username: [Your API Key]
+Password: [Your API Secret]
+```
+
+### hMailServer Configuration Steps
+
+1. Open hMailServer Administrator
+2. Navigate to **Services** → **SMTP**
+3. Click **Relay** tab
+4. Configure the following:
+   - ✅ Enable relay
+   - Relay server: `smtp-relay.mailjet.com`
+   - Port: `587`
+   - Connection security: `STARTTLS`
+   - ✅ Require authentication
+   - Username: [API Key]
+   - Password: [API Secret]
+5. Click **Save**
+
+## SMTP Routes Configuration
+
+### Why Routes Are Needed
+Without routes configured, hMailServer sends ALL outbound SMTP traffic through the relay, including:
+- Emails addressed to local domains
+- This causes unnecessary relay usage
+- Can trigger relay service abuse detection
+
+### Route Configuration for Local Domain
+
+1. In hMailServer Administrator, go to **Routes**
+2. Click **Add Route**
+3. Fill in:
+   ```
+   Route Name: Local delivery for assettrackr.co
+   Domains: assettrackr.co
+   Deliver to: Local delivery
+   ```
+4. Click **OK**
+
+### Route Configuration for Other Domains
+If you have additional domains hosted on this server, add separate routes for each:
+```
+Domain: [your-domain.com]
+Deliver to: Local delivery
+```
+
+### Route for External/Relay Traffic
+All other domains (not matching any route) will automatically use the SMTP relay configuration.
+
+## Verification Steps
+
+### 1. Check Routes Are Active
+```
+hMailServer Administrator → Routes → Verify route list
+```
+Expected: `assettrackr.co` should appear with "Local delivery" destination
+
+### 2. Test Local Delivery
+Send an email to `john@assettrackr.co` from an external account (e.g., ProtonMail)
+- Email should appear in local mailbox
+- Check Mailjet account - sender address should NOT appear in outbound logs
+
+### 3. Test Relay Functionality
+Send an email FROM your hMailServer to an external address (e.g., Gmail)
+- Email should be delivered successfully
+- Check Mailjet account - should appear in outbound logs
+
+## Troubleshooting
+
+### Email Not Delivering Locally
+- Verify route is enabled
+- Check domain is correctly specified
+- Ensure hMailServer service is running
+
+### Relay Not Working
+- Verify SMTP credentials are correct
+- Check port 587 is not blocked by firewall
+- Verify STARTTLS is enabled in connection security
+- Check Mailjet account status
+
+### Relay Still Being Used for Local Emails
+- Double-check route configuration
+- Ensure no other routes are conflicting
+- Restart hMailServer SMTP service after route changes
+
+## Security Notes
+
+- Always use STARTTLS or SSL/TLS - never use "None"
+- Rotate API credentials periodically
+- Monitor Mailjet usage for unauthorized activity
+- Consider enabling IP restrictions on Mailjet relay if supported
@@ -0,0 +1,97 @@
+# hMailServer Configuration Project
+
+## Overview
+Project to document and track hMailServer SMTP relay configuration issues and resolution.
+
+## Background
+
+### Problem
+John's hMailServer was configured to use Mailjet as an SMTP relay for outbound email. However, Mailjet disabled the account because they detected emails being sent from "suspicious/banned" addresses.
+
+### Initial Discovery
+When investigating, John found that the flagged emails were all addresses that had sent spam TO his server (john@assettrackr.co), not emails he was sending out. This was confusing because:
+
+1. Emails addressed TO his domain should be received locally, not sent back out through the relay
+2. Mailjet shouldn't have seen these messages if they were inbound only
+
+### Root Cause
+The issue was that hMailServer was not configured with proper SMTP routes to distinguish between:
+- **Local traffic** - emails destined for domains hosted on this server (should be delivered locally)
+- **Remote traffic** - emails for external domains (should be relayed through Mailjet)
+
+Without this routing configuration, all outbound SMTP traffic was being sent through the relay, including what should have been local deliveries.
+
+## Configuration Details
+
+### hMailServer SMTP Relay Settings (Before Fix)
+```
+Relay server: smtp-relay.mailjet.com
+Port: 587
+Connection security: STARTTLS (changed from None)
+Authentication: Required
+Username: [API Key]
+Password: [API Secret]
+```
+
+### Solution: SMTP Routes Configuration
+
+Created route configuration in hMailServer to mark `assettrackr.co` as a local domain.
+
+**Location in hMailServer:**
+- hMailServer Administrator → Routes → Add Route
+
+**Route Configuration:**
+```
+Domain: assettrackr.co
+Deliver to: Local delivery
+```
+
+This tells hMailServer that any email addressed to `@assettrackr.co` should be delivered locally to the mailbox, NOT sent out through the SMTP relay.
+
+## Files Created
+
+### /workspace/Projects/hmailserver-configuration/README.md
+This file - project documentation
+
+### /workspace/Projects/hmailserver-configuration/ROUTING-SOLUTION.md
+The solution documentation (this file)
+
+### /workspace/Projects/hmailserver-configuration/HMAILSERVER-CONFIG.md
+Detailed configuration reference
+
+## Links & References
+
+- **hMailServer SMTP Relay Configuration Guide:** https://techssh.com/self-hosting/configure-hmailserver-with-smtp-relay/
+  - Section #4 covers SMTP routes configuration
+  - Demonstrates how to mark local domains vs remote domains
+
+- **Mailjet SMTP Documentation:** https://dev.mailjet.com/email/guides/transmission/smtp/
+  - SMTP relay endpoint: smtp-relay.mailjet.com
+  - Port 587 with STARTTLS
+
+- **hMailServer Routes Documentation:** https://www.hmailserver.com/documentation/latest/?page=routes
+
+## Testing
+
+### Test Performed
+John sent an email from ProtonMail to `john@assettrackr.co` and confirmed:
+1. ✅ Email was delivered locally to the mailbox
+2. ✅ The ProtonMail sender address did NOT appear on the Mailjet relay account
+3. ✅ This confirms the routing fix is working correctly
+
+## Lessons Learned
+
+1. **SMTP relay configuration requires route definitions** - Simply setting up the relay credentials isn't enough. You must explicitly tell hMailServer which domains should be delivered locally vs relayed.
+
+2. **Inbound emails shouldn't be relayed** - Emails addressed to local domains should NEVER be sent out through an SMTP relay. They should be delivered directly to local mailboxes.
+
+3. **Security best practices:**
+   - Always use STARTTLS or SSL/TLS for SMTP relay connections
+   - Never use "None" for connection security
+   - Regularly rotate API credentials
+   - Monitor relay usage to detect unauthorized access
+
+## Status
+✅ RESOLVED
+
+The SMTP routing has been configured and tested. Local domains are now properly delivered locally instead of being sent through the Mailjet relay.