Measuring Lifecycle Emails With Koltrix Delivery Events

queued → sent      (the receiving server accepted it)
       ↘ bounced   (hard bounce, recipient auto-suppressed)

const res = await fetch("https://api.koltrix.com/api/v2/emails", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.KOLTRIX_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": `onboarding-day3-${user.id}`,
  },
  body: JSON.stringify({
    from: "[email protected]",
    to: [user.email],
    subject: "Your workspace is set up. Here's the next step",
    body_html: html,
    body_text: text,
  }),
});
const { id } = await res.json();

await db.query(
  `insert into lifecycle_sends (message_id, user_id, email_key, sent_at)
   values ($1, $2, $3, now())`,
  [id, user.id, "onboarding_day3"],
);

Step 2: receive and verify events#

Every webhook payload is signed with HMAC-SHA256 using a per-endpoint secret, sent in the X-Koltrix-Signature header as sha256= plus the hex digest of the raw request body. Verify it before storing anything:

import crypto from "node:crypto";

app.post("/hooks/koltrix", express.raw({ type: "application/json" }), async (req, res) => {
  const expected = "sha256=" + crypto
    .createHmac("sha256", process.env.KOLTRIX_WEBHOOK_SECRET)
    .update(req.body)
    .digest("hex");
  const got = req.get("X-Koltrix-Signature") ?? "";
  if (expected.length !== got.length ||
      !crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(got))) {
    return res.sendStatus(401);
  }
  res.sendStatus(200); // acknowledge fast, process after
  const evt = JSON.parse(req.body.toString());
  await db.query(
    `insert into email_events (message_id, event, occurred_at)
     values ($1, $2, to_timestamp($3))
     on conflict (message_id, event, occurred_at) do nothing`,
    [evt.message_id, evt.event, evt.timestamp],
  );
});

Three details from the webhook docs are worth building in from day one:

• Use the raw body. If your framework parses JSON first, the signature won't match.
• Respond quickly, and keep your endpoint up. Each event is attempted once, with an 8-second timeout. There are no retries, so an event that hits a deploy, an outage or a slow handler is simply missed. Acknowledge first and process afterwards, as the handler above does.
• Treat events as a signal, not a ledger. Because a missed event isn't redelivered, don't build billing or anything critical on webhooks alone. For a message you care about, poll its status. Keeping the insert idempotent, as the on conflict clause does, is still cheap insurance.

Step 3: measure outcomes, not opens#

With sends and events in your database, the useful questions become simple joins against your own product data.

Did the onboarding email cause activation? Compare the activation rate of users who received onboarding_day3 with a small holdout group who didn't. message.sent and message.bounced tell you who it actually reached.

Is the trial-ending email converting? For each trial_ending send, check whether the workspace upgraded within a few days of it being sent. Clicks on the upgrade link are a useful leading indicator.

Is the dunning sequence recovering revenue? Join dunning_* sends to payment-retry results. Clicks on the update-card link show which email in the sequence does the work.

Is any email unwelcome? Koltrix doesn't send complaint or unsubscribe events, so build this signal from your own data. Record unsubscribes from your own preference page against the email key that linked to it. Count replies that land in your inbox asking you to stop. Watch bounces per email key, and watch for an email whose sends keep going out while clicks and product outcomes stay flat. One email that consistently underperforms the rest of the sequence on all of those is worth rewriting or cutting.

Why opens deserve suspicion#

Opens come from a tracking pixel. Some mail clients and privacy features load images automatically, which registers an open whether or not a person read anything. Even a clean open count tells you about attention, not outcomes. Use opens to spot broken emails, such as a message that suddenly gets almost none, not to decide which email works.

When to turn tracking off#

Open and click tracking are on by default. For mail where tracking adds nothing and rewritten links could look odd, like password resets and receipts, the docs describe opting out per message on the SMTP relay with the X-Koltrix-No-Track: 1 header.

A minimal reporting table#

Once events flow in, one query per week covers most lifecycle questions:

The "outcome rate" column is the one that matters, and it's the one only your own data can fill in.

Key takeaways#

• Store the Koltrix message id next to your user and lifecycle step at send time. That mapping is what makes every later question answerable.
• Koltrix sends four events: sent, bounced, opened and clicked. Each is attempted once with no retries, so verify the signature, acknowledge fast and poll status for anything critical.
• Judge lifecycle emails by product outcomes, clicks and your own unsubscribe data, not by open rates.
• Use Idempotency-Key on sends so retries never produce duplicate emails.