smtp.mailkube.com directly. On a cluster with many services, a
small relay alongside them concentrates the moving parts in one container: applications send
plain SMTP to a local address, and the relay handles TLS, authentication, queuing, and retries.
The relay ships as a container image.
Why run a relay
One relay in front of many services moves nine concerns out of each application and into a single place you operate.
It also keeps you inside the platform’s limits without anyone thinking about it: one authenticated
connection carries many messages, so draining a queue never trips the per-domain authentication
rate limit. The relay’s own connection budget is covered under Configuration.
Quick start
Credentials
The relay authenticates to mailkube with an ordinary SMTP credential, under the same rules.
Both
_FILE forms strip trailing whitespace, because kubectl create secret --from-file on a file
written with echo embeds a newline, which is the most common cause of a 535 here. A missing or
unreadable file stops the container.
Configuration
Every setting is an environment variable. The upstream host is hardcoded: there is no variable and no build argument for it, and the only accepted submission port is 587.Upstream and ingress
Limits and pacing
The relay paces itself to your plan’s send rate. Each lane carries up to one message per second, so
the lane count is the rate in messages per second.
Lanes exist because Postfix paces in whole seconds. One delivery stream can therefore never exceed one
message per second, so the relay runs several paced streams and spreads messages across them. A lane’s
pacing also pins its own concurrency to one, which is why
RELAY_CONCURRENCY governs nothing until you
set RELAY_LANES=0.
At RELAY_LANES=0 the relay sends as fast as the network allows, and every message over your plan’s
rate returns 450 4.7.1. Those rejections count against your sending address, so treat it as a
deliberate choice.
Behavior and lifecycle
ENFORCE_FROM_DOMAIN is a migration aid, not a recommendation. It turns a hard 550 from a
legacy application into a working send, so wordpress@localhost leaves as
[email protected]. The correct fix is for the application to send a compliant From.Deployment
There are two topologies:
Kubernetes, OpenShift, and Docker Compose manifests are published with the image, including a
hardened read-only deployment and a NetworkPolicy.
mailkube/mailkube-docker
Source, full configuration reference, and deployment examples.
/var/spool/postfix is the queue and is the one that must persist, or mail
in flight is lost when the container is replaced. /var/lib/postfix holds Postfix’s own state and
must be per instance: Postfix refuses to start if it finds another running instance’s state
there, so never share that volume.
Security
The relay refuses to start if it is configured to accept every address, and it connects to mailkube with mandatory, certificate-verified TLS.Requiring authentication
If you would rather not rely on network isolation alone, the relay can require clients to authenticate. This is useful when other workloads share the namespace, or when a NetworkPolicy is not enforced by your CNI.AUTH PLAIN and AUTH LOGIN
are offered.
Certificates are mounted, never generated. When a certificate is present the relay refuses
AUTH
until the channel is encrypted, so a client cannot be downgraded into sending its password in the
clear. Enabling authentication without a certificate still works, and the relay warns at startup
that passwords cross your network base64-encoded rather than encrypted.RELAY_AUTH_REQUIRED=yes needs at least one account configured, or the relay refuses to start;
a relay with no accounts would reject every client, its own health probe included.
This is separate from the credential the relay uses to authenticate to mailkube, which is always
required.
If your credential uses a source IP allowlist, add your cluster’s egress address: mailkube sees the
cluster’s shared NAT address.
Headers and limits
The relay passes theX-Mailkube-* headers through unchanged, so
templates, topics, and
tags behave exactly as they do on a direct connection.
Keep every physical header line at or below 998 bytes, including the field name. SMTP breaks
longer lines at a fixed offset regardless of token boundaries, which can silently corrupt a large
X-Mailkube-Template-Variables value. For larger payloads, use the REST API.