> ## Documentation Index
> Fetch the complete documentation index at: https://docs.telaven.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Send your first SMS in about five minutes. You need an API key and one HTTP request, and no SDK.

**1. Create an API key**

Sign in at [app.telaven.com](https://app.telaven.com), open **Settings → API keys** and select **Create API key**.
Copy the key; it starts with `tlv_` and is shown only once.

Keep it in an environment variable on your server:

```bash theme={null}
export TELAVEN_API_KEY="tlv_your_api_key_here"
```

**2. Check the key works**

`GET /balance` is a safe first call. It confirms the key and shows how many SMS your wallet covers.

```bash theme={null}
curl https://app.telaven.com/api/v1/balance \
  -H "Authorization: Bearer $TELAVEN_API_KEY"
```

```json theme={null}
{
  "success": true,
  "data": {
    "balanceKes": "14437.50",
    "totalLoadedKes": "15000.00",
    "totalSpentKes": "562.50",
    "smsRateKes": "0.90",
    "smsSendable": 16041
  }
}
```

**3. Send an SMS**

```bash cURL theme={null}
curl -X POST https://app.telaven.com/api/v1/sms/send \
  -H "Authorization: Bearer $TELAVEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["0712345678"],
    "message": "Hello from Messaly! This is my first SMS."
  }'
```

```javascript Node.js theme={null}
const res = await fetch("https://app.telaven.com/api/v1/sms/send", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.TELAVEN_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    to: ["0712345678"],
    message: "Hello from Messaly! This is my first SMS.",
  }),
});
console.log(await res.json());
```

```python Python theme={null}
import os, requests

res = requests.post(
    "https://app.telaven.com/api/v1/sms/send",
    headers={"Authorization": f"Bearer {os.environ['TELAVEN_API_KEY']}"},
    json={
        "to": ["0712345678"],
        "message": "Hello from Messaly! This is my first SMS.",
    },
)
print(res.json())
```

```php PHP theme={null}
<?php
$ch = curl_init("https://app.telaven.com/api/v1/sms/send");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("TELAVEN_API_KEY"),
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "to" => ["0712345678"],
        "message" => "Hello from Messaly! This is my first SMS.",
    ]),
]);
print_r(json_decode(curl_exec($ch), true));
```

```csharp C# theme={null}
using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue(
    "Bearer", Environment.GetEnvironmentVariable("TELAVEN_API_KEY"));

var payload = JsonSerializer.Serialize(new
{
    to = new[] { "0712345678" },
    message = "Hello from Messaly! This is my first SMS.",
});
using var res = await http.PostAsync(
    "https://app.telaven.com/api/v1/sms/send",
    new StringContent(payload, Encoding.UTF8, "application/json"));
Console.WriteLine(await res.Content.ReadAsStringAsync());
```

**4. Read the response**

```json theme={null}
{
  "success": true,
  "campaignId": "6f1c…",
  "totalSent": 1,
  "totalFailed": 0,
  "balanceKes": "14436.60",
  "recipients": [
    {
      "id": "a3d2…",
      "to": "+254712345678",
      "status": "sent",
      "messageId": "ATXid_8f3…",
      "cost": "KES 0.90",
      "error": null,
      "sentAt": "2026-11-12T09:30:01.000Z"
    }
  ]
}
```

`status: "sent"` means the network accepted the message. Delivery is confirmed later: poll
[`GET /sms/messages/{id}`](https://docs.telaven.com/api-reference/sms/get-message) with the recipient `id`, or subscribe to the
`sms.delivered` and `sms.failed` [webhooks](https://docs.telaven.com/guides/webhooks.md).

## Next steps

> [card] [Authentication](https://docs.telaven.com/get-started/authentication.md)
>
> Scopes, IP allowlists and keeping keys safe.

> [card] [SMS campaigns](https://docs.telaven.com/guides/sms-campaigns.md)
>
> Send to lists and tags, now or on a schedule.

> [card] [Webhooks](https://docs.telaven.com/guides/webhooks.md)
>
> Delivery reports and replies, pushed to you.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.