Skip to main content
Applications can connect to 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

Then point your application at the relay. Plain, unauthenticated SMTP on port 25:

Credentials

The relay authenticates to mailkube with an ordinary SMTP credential, under the same rules.
The username must include the domain, and the password is the SMTP credential’s secret rather than an API key. The relay refuses to start if the username has no @, and warns if the password looks like an API key.
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.
The default caps sending at about four messages per second. Releases before 2.0 did not pace at all. On any plan above Free, raise RELAY_LANES to the rate in the table, or your plan’s capacity goes unused.
Connection budget: 2 × RELAY_LANES × instances ≤ 18, or instances × RELAY_CONCURRENCY ≤ 9 when pacing is off. mailkube’s edge admits 20 concurrent connections per source IP, and that is your cluster’s shared egress address, not per pod. Each lane holds two upstream connections, one delivering and one cached idle for reuse, so two replicas at the default four lanes hold 16 of the 20 and a third exceeds the budget. In sidecar mode “instances” is your application pod count. See Connection limits for the edge limits themselves.
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.
Two paths hold state. /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’s listener is unauthenticated by default. Anything that can reach it can send mail as your verified domain, so it must never be exposed outside your cluster. Restrict access with a NetworkPolicy or an equivalent control, and never publish the port to the internet.
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.
Clients then send a normal username and password over STARTTLS; both 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 the X-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.
Rate limits and plan limits are unchanged by the relay. It queues and retries when it reaches them, and the limits themselves still apply.