Add Metadata to Webhooks

KumoMTA Configuration
1

Quick question. I didn’t see any information in the docs AND I realize that I am coming in hot as the newb, but… I would like my internal org_id and campaign_id returned to me from the webhook. How do I pass those values through the REST API for sending so that I can have them back in my webhook.

3

For the sake of documenting on searches in the future, I think that the answer lies in trace headers.

So if I add a value as a trace header like this:
https://docs.kumomta.com/reference/http/api_inject_v1/#trace_headers

And then pull those headers for the webhook using Luascript. Now I am testing.

4

So I have testing with trace_headers and it seems like the solution is

Includ_meta_names

include_meta_names = {},```

But the docs providers are lua, and I am passing JSON in my payload, following these docs:

https://docs.kumomta.com/reference/http/api_inject_v1/#trace_headers

I tried sending an array

include_meta_names: ["x_org_id"]

Which I am adding as meta:

-- Read trace headers (may return nil if absent)
local campaign_id = msg:get_header("X-Campaign-ID")
local org_id = msg:get_header("X-Org-ID")

-- Insert into the record
record["x_campaign_id"] = campaign_id
record["x_org_id"] = org_id


Kind of stuck right now.
5

So trace headers are about having that information survive an FBL redaction by virtue of the x-KumoRef header.

6

You’re looking to log what you provided.

7

Do you have the filling of the headers working?

8

As in the X headers appear in the message?

9

If so you need import_x_headers - KumoMTA Docs

10

That will put the X headers in meta, then you can use meta - KumoMTA Docs to get them into your logging.

11

Yes, the headers are coming through in my payload and in the delivered message.

X-Mailer: 3mails.ai
X-Org-ID: id_an6wp2x0s
X-offerExpired: 2025-12-12T15:07:50.209Z```

I thought that I had the filling of the headers working.  You can see that I commented ou the import_x_headers(), but I tried it with and without.

```kumo.on("message_accepted", function(msg)

    --msg:import_x_headers()

    -- Create a log_record metadata table if it doesn't exist yet
    local record = msg:get_meta("log_record") or {}

    -- Read trace headers (may return nil if absent)
    local campaign_id = msg:get_header("X-Campaign-ID")
    local org_id = msg:get_header("X-Org-ID")

    -- Insert into the record
    record["x_campaign_id"] = campaign_id
    record["x_org_id"] = org_id

    -- Save it back to metadata
    msg:set_meta("log_record", record)
end)```


I feel like I am missing something.
12

Where did you get that code?

13

There is no “message_accepted” event, that code will never fire.

14

Stupid AI

15

msg:import_x_headers() should in either http_message_generated or smpt_server_message_received I believe

16

Stupid AI
When using AI assisted coding with kumo, I’ve only had good results with claude code. I always plan before coding. Give it links to the relevant kumo docs, RFCs, etc and ask it to research before it provides a solution. In that workflow it does pretty well.

17

Fair enough

18

My other tip for that: I also keep the kumo source code checked out locally. If I can’t figure out the behavior of something I’ll ask it explore the kumo code base directly.

19

Yeah most AI just hallucinates something that looks like it should be working Lua.

20

Almost every time with one shot prompting in my experience.

21

And then point out what the docs lack, right?