# Send Your First Message (/sdks/cpp/tutorials/first-message)



This is your first hands-on lesson with the C++ SDK: create a client, send an event, and receive it. Make sure you have the SDK installed (see the [C++ SDK overview](/sdks/cpp)).

## Create a Client [#create-a-client]

```cpp title="main.cc"
#include <iostream>
#include "kubemq/kubemq.h"

int main() {
    kubemq::ClientOptions opts;
    opts.set_address("localhost", 50000);
    opts.set_client_id("my-app");

    auto client_or = kubemq::Client::Create(opts);
    if (!client_or.ok()) {
        std::cerr << "Connect failed: " << client_or.status().ToString() << "\n";
        return 1;
    }
    auto& client = *client_or;

    auto ping_or = client->Ping();
    if (ping_or.ok()) {
        std::cout << "Connected to: " << ping_or->host
                  << " v" << ping_or->version << "\n";
    }

    auto close_status = client->Close();
    if (!close_status.ok()) {
        std::cerr << "Close failed: " << close_status.message() << "\n";
    }
    return 0;
}
```

## Send Your First Event [#send-your-first-event]

```cpp title="send_event.cc"
auto event_or = kubemq::Event::Builder()
    .SetChannel("notifications")
    .SetBody("hello kubemq")
    .SetMetadata("greeting")
    .Build();
if (!event_or.ok()) {
    std::cerr << "Build failed: " << event_or.status().ToString() << "\n";
    return 1;
}

auto status = client->SendEvent(*event_or);
if (!status.ok()) {
    std::cerr << "Send failed: " << status.ToString() << "\n";
}
std::cout << "Event sent successfully\n";
```

## Receive Events [#receive-events]

```cpp title="receive_events.cc"
auto sub_or = client->SubscribeToEvents("notifications", "",
    [](const kubemq::EventReceive& event) {
        std::cout << "Received: " << event.body << "\n";
    },
    [](const kubemq::Status& err) {
        std::cerr << "Error: " << err.message() << "\n";
    });
if (!sub_or.ok()) {
    std::cerr << "Subscribe failed: " << sub_or.status().ToString() << "\n";
    return 1;
}
auto& sub = *sub_or;

// When done:
sub->Cancel();
```

## Configuration Options [#configuration-options]

| Option                      | Default                   | Description                   |
| --------------------------- | ------------------------- | ----------------------------- |
| `set_address(host, port)`   | `localhost:50000`         | KubeMQ server address         |
| `set_client_id(id)`         | Auto-generated UUID       | Unique client identifier      |
| `set_auth_token(token)`     | None                      | JWT or API key authentication |
| `set_tls_config(config)`    | None (plaintext)          | TLS/mTLS configuration        |
| `set_reconnect_policy(p)`   | Infinite retries, backoff | Reconnection behavior         |
| `set_connection_timeout(d)` | 10s                       | Initial connection timeout    |
| `set_retry_policy(p)`       | Default retry             | Retry for transient failures  |
| `set_logger(l)`             | None                      | Custom logger implementation  |
| `set_tracer_provider(tp)`   | None                      | OpenTelemetry tracer          |
| `set_meter_provider(mp)`    | None                      | OpenTelemetry meter           |

## Error Handling [#error-handling]

The C++ SDK uses `Status` and `StatusOr<T>` return types instead of exceptions. Always check `ok()` before accessing values:

```cpp
auto result = client->SendEvent(event);
if (!result.ok()) {
    std::cerr << "Code: " << static_cast<int>(result.code())
              << " Message: " << result.message()
              << " Retryable: " << result.is_retryable() << "\n";

    switch (result.code()) {
    case kubemq::ErrorCode::kTimeout:
        // Retry with longer timeout
        break;
    case kubemq::ErrorCode::kAuthentication:
        // Check credentials
        break;
    case kubemq::ErrorCode::kTransient:
        // Automatic retry exhausted
        break;
    default:
        break;
    }
}
```

## Next Steps [#next-steps]

* [C++ SDK Reference](/sdks/cpp/reference) -- full API documentation
* [C++ SDK Examples](/sdks/cpp/how-to) -- complete examples for all patterns
* [GitHub Repository](https://github.com/kubemq-io/kubemq-cpp) -- source code and issues