# Events (/sdks/elixir/reference/events)



Events provide fire-and-forget messaging where published messages are delivered to all active subscribers. Events are not persisted — subscribers must be online to receive them.

## Structs [#structs]

### KubeMQ.Event [#kubemqevent]

Used to publish events.

| Field       | Type                     | Description                       |
| ----------- | ------------------------ | --------------------------------- |
| `id`        | `String.t()`             | Auto-generated message ID         |
| `channel`   | `String.t()`             | Target channel name               |
| `metadata`  | `String.t()`             | Optional metadata string          |
| `body`      | `String.t() \| binary()` | Message payload                   |
| `client_id` | `String.t()`             | Sender client ID (auto-populated) |
| `tags`      | `map()`                  | Optional key-value tags           |

### KubeMQ.EventReceive [#kubemqeventreceive]

Received by subscribers.

| Field       | Type                     | Description      |
| ----------- | ------------------------ | ---------------- |
| `id`        | `String.t()`             | Message ID       |
| `channel`   | `String.t()`             | Source channel   |
| `metadata`  | `String.t()`             | Metadata string  |
| `body`      | `String.t() \| binary()` | Message payload  |
| `timestamp` | `integer()`              | Server timestamp |
| `sequence`  | `integer()`              | Sequence number  |
| `tags`      | `map()`                  | Key-value tags   |

## Publishing [#publishing]

```elixir
event = KubeMQ.Event.new(
  channel: "notifications",
  body: "hello kubemq",
  metadata: "greeting",
  tags: %{"source" => "elixir"}
)

:ok = KubeMQ.Client.send_event(client, event)
```

## Stream Publishing [#stream-publishing]

Open a persistent stream for efficient high-throughput sending:

```elixir
{:ok, handle} = KubeMQ.Client.send_event_stream(client)
:ok = KubeMQ.EventStreamHandle.send(handle, event)
KubeMQ.EventStreamHandle.close(handle)
```

## Subscribing [#subscribing]

```elixir
{:ok, sub} = KubeMQ.Client.subscribe_to_events(client, "notifications",
  on_event: fn event -> IO.puts("Got: #{event.body}") end,
  on_error: fn err -> IO.puts("Error: #{err.message}") end,
  group: "my-group"
)

KubeMQ.Subscription.cancel(sub)
```

## See Also [#see-also]

* [Events Examples](/sdks/elixir/how-to/events/)
* [Events Pattern Overview](/learn/events/)