MailHubRelay implements a distributed email handling architecture designed to facilitate the conversion and transmission of various input formats into Gmail-compatible email communications. The system comprises three primary components with complementary utility scripts for deployment management.
The central relay server component operates as a standalone service or foreground application, implementing the following functionalities:
- JSON-format email request processing via localhost:2525 (configurable)
- Secure email transmission through Gmail SMTP with TLS encryption
- Comprehensive logging capabilities via the logger package
- Configurable retry mechanisms for enhanced delivery reliability
- External configuration support for deployment flexibility
A command-line interface implementing sendmail-compatible operations:
- Direct compatibility with standard sendmail command-line parameters
- Internal routing through MHRS for standardized email delivery
- Foreground operation mode for immediate feedback
- Configuration inheritance from system-wide settings
Web service implementation for form submission processing:
- HTTP endpoint exposure on port 8845 (configurable)
- CORS-compatible security framework
- JSON request handling with validation
- Configurable operation modes: service or foreground application
- Gmail account with domain verification
- Configured sender email alias
- Application-specific password (Google Account > Security > App Passwords)
- TLS-enabled communication capability
- Outbound access to port 587 (Gmail SMTP)
- Local port 2525 (MHRS internal communication)
- Port 8845 (SubmitF form submission handling)
- Appropriate firewall rules for specified ports
Clone or fork the repository.
Use standard go build process, or use make.sh script to with pre-defined make config for freebsd/amd64 build:
# Build script use for FreeBSD build
./script/make.sh -c mhrs.make # Mail Hub Relay Server
./script/make.sh -c mhrc.make # Mail Hub Relay Client
./script/make.sh -c submitf.make # Submit Form HandlerThe installation/uninstallation scripts facilitate deployment.
./install-service.sh [-r] [-l] [-c] <path_to_executable>
./uninstall-service.sh [-l] [-c] <service_name>Parameters:
-r: Execute service with root privileges-l: Create and preserve of log directory-c: Create and preserve of configuration directory
Deployment example:
./scripts/install-service.sh mhrs # Mail Hub Relay Server
./scripts/install-service.sh submitf # Form Handler
./scripts/install-app.sh mhrc # Mail Hub Relay ClientFor running on a privileged port (<1024, e.g. 25), install as root (install-service -r).
Default configuration paths (not configurable):
/usr/local/etc/<service_name>/<service_name>.toml- Service-specific directories created automatically
- Default values provided if configuration absent
- Mailer Configuration Update:
# Edit /etc/mail/mailer.conf and /usr/local/etc/mail/mailer.conf
sendmail /usr/local/bin/mhrc
send-mail /usr/local/bin/mhrc
mailq /usr/local/bin/mhrc -bp
newaliases /usr/local/bin/mhrc -bi
hoststat /usr/local/bin/mhrc -bh
purgestat /usr/local/bin/mhrc -bp- Sendmail Service Management:
sysrc sendmail_enable="NO"
sysrc sendmail_submit_enable="NO"
sysrc sendmail_outbound_enable="NO"
sysrc sendmail_msp_queue_enable="NO"- System Integration:
ln -s /usr/local/bin/mhrc /usr/local/sbin/sendmail
ln -s /usr/local/bin/mhrc /usr/sbin/sendmailSuitable for small-medium servers with low email traffic.
[Gmail SMTP]
|
................................................ [Internet] .................
| ^ ^ ^
v v | v
................................................ [Firewall] .................
| ^ ^ ^
v v | |
......................................................:SSL [NGINX] |:TLS
| ^ ^ |
v v | v
[MHRC] [SubmitF] [Local Apps] [Website] [MHRS]
| | | ^
v v v |
-------------------------------------------------------------------
Data Flow Patterns:
A. Web Form Submission Path: Website form submission -> NGINX -> SubmitF -> MHRS -> Gmail SMTP
B. Local Application Path: Local Apps -> MHRS -> Gmail SMTP
C. Legacy Application Path: Sendmail Apps -> MHRC -> MHRS -> Gmail SMTP
Foreground execution:
mhrsStandard sendmail syntax support:
# Direct recipient specification
echo "Message content" | mhrc [email protected]
# Header-based routing
echo -e "To: [email protected]\nSubject: Test\n\nMessage" | mhrc -t
# Subject specification
echo "Message content" | mhrc -s "Subject" [email protected]Foreground execution:
submitfnginx configuration example:
# Contact form submission endpoint with rate limiting
location /submit {
proxy_pass http://localhost:8845;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header Host $host;
limit_req zone=one burst=5 nodelay;
}async function submitForm(event) {
event.preventDefault();
const formData = {
name: document.getElementById('name').value,
email: document.getElementById('email').value,
message: document.getElementById('message').value
};
try {
const response = await fetch('http://localhost:8845/submit', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify(formData)
});
if (!response.ok) {
throw new Error('Submission failed');
}
alert('Form submitted successfully');
} catch (error) {
console.error('Error:', error);
alert('Failed to submit form');
}
}This project emerged from challenges in setting up mail servers in cloud environments. After experimenting with various solutions, several issues became apparent:
- Port 25 is blocked by major cloud providers, forcing reliance on relay services
- Traditional mail servers are complex to configure and tend to fallback to port 25
- Existing lightweight alternatives lacked features, or had dependencies and complexities unsuitable for simple automated email needs
MailHubRelay offers a streamlined solution by acting as an aggregator and mail agent for automated emails, relaying them through Gmail's SMTP service.
MIT license