Mailrelay turns incoming email into webhooks for self-hosted automation

On October 24, 2026, developer gowthamgts released mailrelay, an open-source incoming mail server designed to bridge the gap between traditional email protocols and modern HTTP-based automation. This self-hosted solution allows users to receive emails, parse their content, and trigger webhooks according to specific rules, enabling seamless integration with homelab services and small business tools that do not natively support email ingestion.

What happened

The release introduces a lightweight SMTP server written in Go that acts as a relay for incoming messages. Instead of storing emails in a traditional mailbox for human reading, mailrelay evaluates each message against user-defined conditions and forwards the data to specified webhook URLs. The system is designed to be resilient; it acknowledges receipt of an email immediately with a 250 OK response, while the actual webhook delivery happens asynchronously in the background. This ensures that temporary failures or slow responses from downstream services do not cause the original email to bounce.

The project provides multiple deployment options to suit different infrastructure preferences. Users can run it via Docker, where the web interface is enabled by default, or as a standalone binary built from source. The application stores all operational data, including a SQLite database, raw .eml files, and configuration settings, within a single /data directory. This structure simplifies backups and migration for self-hosters who prefer minimal dependency management. A quick-start Docker Compose file is available to help users test the functionality with a sample echo server before connecting it to real services.

Key details

• Rule-based routing: Users can create rules in the web UI that match emails based on fields like From, To, Subject, Body, headers, or SMTP envelope addresses. Patterns support globs and regular expressions.
• Async delivery with retries: Webhooks are sent in the background with exponential backoff. Every attempt is recorded, and failed deliveries can be replayed manually from the interface.
• Security defaults: By default, webhooks cannot reach private networks, localhost, or cloud metadata endpoints. This restriction can be lifted via environment variables for internal service integration.
• Authentication support: The web UI supports OpenID Connect (OIDC) providers such as Google, Okta, and Authentik for secure access, though GitHub login is not supported due to protocol limitations.
• Flexible payload formatting: Webhooks receive parsed JSON by default, but users can customize the output using Go templates with functions for joining lists or setting fallback values.
• Email verification: The server performs SPF, DKIM, and DMARC checks, with options to log or enforce these policies. It also verifies ARC headers to preserve authentication results for forwarded mail.

Background

For many years, integrating email into automated workflows required complex middleware or reliance on third-party SaaS platforms. Traditional SMTP servers are designed for human-to-human communication, storing messages in mailboxes rather than triggering code execution. Webhooks, conversely, are the standard for machine-to-machine communication, allowing applications to send real-time data over HTTP. Mailrelay bridges this divide by acting as an SMTP endpoint that translates email events into HTTP requests.

This approach is particularly valuable for self-hosted environments where privacy and control are priorities. Instead of granting a cloud service access to sensitive financial alerts or support tickets, organizations can keep the entire pipeline within their own network. The tool handles the complexities of email parsing, including attachment extraction and header analysis, presenting the data in a clean JSON format that modern applications can easily consume.

Why it matters

Teams running their own software often struggle to connect legacy email-based notifications with modern dashboards and automation tools. For example, bank alerts, shipping notifications, or system monitoring emails typically land in an inbox, requiring manual intervention to act upon. Mailrelay allows these messages to automatically trigger actions in tools like Home Assistant, Paperless-ngx, or custom APIs. This reduces manual workload and ensures that critical information is processed immediately without human delay.

Furthermore, the ability to replay webhooks is a significant operational advantage. In distributed systems, network glitches or service restarts can cause webhook deliveries to fail. Without a retry mechanism, these events are lost forever. Mailrelay records every attempt and allows administrators to resend specific emails from the UI, ensuring data consistency. The default security posture, which blocks access to private networks unless explicitly allowed, also protects against accidental internal exposure when configuring external-facing services.

What you can do

• Deploy the quick-start Docker Compose stack to test the SMTP listener and webhook echo server locally.
• Configure smtp.allowed_recipients to restrict the server to only accept emails for your specific domains or addresses.
• Set up OIDC authentication for the web UI using providers like Authentik or Keycloak to secure administrative access.
• Use Go templates in the rule configuration to strip unnecessary headers and reduce the payload size sent to your downstream services.
• Enable webhook.allow_private_networks only if your target automation services reside on the same local network or Docker bridge.
• Monitor the /metrics endpoint with Prometheus to track email volume, webhook success rates, and retry counts.