Relay

The relay/ folder runs a second KumoMTA instance: an SMTP relay that your apps and servers send through. It is built for the internet:

• Every message needs a username and password. There is no IP-based trust.
• Each account can only send for its own domains.
• Every event for an account's mail goes to that account's webhook, and to no other.

app ──2587 STARTTLS + AUTH──▶ KumoMTA ──DKIM──▶ queue ──▶ recipient's MX (or a smarthost)
                                 │
                                 └──▶ the account's webhook (signed JSON, one POST per event)

It is separate from the outbound service, with its own port, spool and logs.

Files

Everything KumoMTA reads is in relay/policy/, mounted read-only at /opt/kumomta/etc/policy.

Run it

From the repository root:

cp relay/.env.example relay/.env
cp relay/policy/users.example.lua relay/policy/users.lua
# edit both files, then:
docker compose -f deploy/docker-compose.yml up -d relay
docker compose -f deploy/docker-compose.yml logs -f relay

Queued mail and pending webhook events are kept in the relay-spool volume, so they survive a rebuild.

Accounts

relay/policy/users.lua holds one entry per account:

return {
  ["app1"] = {
    password = "change-me",
    domains = { "example.com" },
    webhook = {
      url = "https://app1.example.com/webhooks/mail",
      secret = "change-me",
      events = { "Reception", "Delivery", "TransientFailure", "Bounce", "Expiration" },
    },
  },
}

If an account has a webhook without a url or a secret, the account is turned off and its logins fail. The reason is written to the relay's log. Changes to users.lua apply within a minute, without a restart.

Send mail

Both the envelope sender (MAIL FROM) and the From header must be in the account's domains. The relay DKIM-signs the message for the From domain.

const transport = nodemailer.createTransport({
  host: "relay.example.com",
  port: 2587,
  requireTLS: true,
  auth: { user: "app1", pass: "change-me" },
});
 
await transport.sendMail({
  from: "hello@example.com",
  to: "someone@gmail.com",
  subject: "Hi",
  text: "Hello",
  headers: { "X-Trace-Id": "order-1234", "X-Campaign": "welcome" },
});

Two optional headers help you match events to your own records. The relay removes both before it delivers the message.

The 250 reply ends with the relay's message ID for each recipient (OK ids=<id> ...). It is the same value as id in the events.

Rejections

Rejections after a successful login are also sent to the account's webhook as Rejection events.

Webhook

The relay sends one POST per event. The body is a KumoMTA log record:

{
  "type": "Bounce",
  "id": "65f291aedeea11f194609a64d9b217fd",
  "sender": "hello@example.com",
  "recipient": "someone@example.net",
  "queue": "welcome:app1@example.net",
  "response": { "code": 556, "content": "...", "enhanced_code": { "class": 5, "subject": 1, "detail": 10 } },
  "timestamp": 1794523393,
  "num_attempts": 1,
  "meta": {
    "authn_id": "app1",
    "x_trace_id": "order-1234",
    "campaign": "welcome",
    "received_from": "198.51.100.7:49652"
  },
  "headers": { "Message-ID": "<...>", "Subject": "Hi", "From": "hello@example.com", "To": "someone@example.net" }
}

type is one of Reception, Delivery, TransientFailure, Bounce, Expiration, Rejection, AdminBounce or Delayed, plus a few rarer types described in the log record reference.

Each request has these headers:

Your response

Pending events are stored in the spool, so a restart does not lose them.

Check the signature

Verify the signature against the raw body before you parse it:

const crypto = require("crypto");
 
function verifyRelayWebhook(rawBody, headers, secret) {
  const timestamp = headers["x-relay-timestamp"];
  const expected =
    "sha256=" +
    crypto.createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");
  const given = Buffer.from(headers["x-relay-signature"] || "");
  const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) < 300;
  return fresh && given.length === expected.length && crypto.timingSafeEqual(given, Buffer.from(expected));
}

The timestamp check rejects old requests that someone replays.

Delivery

By default the relay delivers to each recipient's mail server, with the per-provider rate limits that ship with KumoMTA. To change them, add relay/policy/shaping.toml.

To send everything through another server instead, set RELAY_SMARTHOST, plus RELAY_SMARTHOST_PORT, RELAY_SMARTHOST_USER and RELAY_SMARTHOST_PASS if it needs a login. To go through this stack's outbound service:

RELAY_SMARTHOST=outbound
RELAY_SMARTHOST_PORT=587
RELAY_SMARTHOST_USER=user1
RELAY_SMARTHOST_PASS=change-me
RELAY_SMARTHOST_TLS=RequiredInsecure

RequiredInsecure is needed because outbound uses a self-signed certificate. Set DKIM_BACKEND=none if the smarthost signs the mail.

All settings are listed in Environment variables.

Limits

• Passwords in users.lua are stored in plain text.
• There are no per-account rate limits yet.
• A connection that fails before it logs in has no account, so it only appears in the relay's own logs (the relay-logs volume).
• If you remove an account or its webhook, the account's pending events are dropped.
• A bounce that a remote server sends later, after accepting the mail, goes to the envelope sender's domain, not to the relay.