# Send your first SMS in 5 minutes

This guide takes you from an API key to a delivered message, with curl or the Node SDK.

## 1. Create an API key

In the portal: **API → Keys → New key**. Two kinds exist:

| Kind | Prefix | Behaviour |
| --- | --- | --- |
| Live | `bm_live_` | Really sends and charges credits |
| Test | `bm_test_` | Full validation, never sends, never charges — see [Test mode](https://smsprovider-web.vercel.app/docs/test-mode) |

The full key is shown once. Keep it in an environment variable (`BATLER_API_KEY`), never in client-side code.

## 2. Make sure you have a verified sender

Every message is sent from an approved sender name: a shared name from the system list, or a name approved for your account. New names are requested in the portal (Sender names → request a new name): capital Latin letters, up to 10 characters, with a business certificate and an ID document. You get an answer within one business day. [GET /senders](https://smsprovider-web.vercel.app/docs/api/list-senders) returns the full list.

## 3. Send a message

```bash
curl -X POST https://smsprovider-web.vercel.app/api/v1/messages \
  -H "Authorization: Bearer $BATLER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"to": "0501234567", "from": "MyBrand", "body": "Hi! Your order has shipped"}'
```

Or with the SDK:

```ts
import { BatlerSMS } from "@batler/sms";

const sms = new BatlerSMS({ apiKey: process.env.BATLER_API_KEY! });
const res = await sms.messages.send({ to: "0501234567", from: "MyBrand", body: "Hi! Your order has shipped" });
console.log(res.messages[0].id);
```

The response comes back immediately, before the actual send:

```json
{
  "batch_id": "7d1c3c5e-2b1f-4c55-9a51-1f0b8f1b2a10",
  "accepted": 1,
  "rejected": [],
  "credits_reserved": 1,
  "messages": [{ "id": "0e9b2f0a-6c1d-4f43-8c33-6f3b3f0d9a11", "status": "queued", "to": "+972501234567", "segments": 1, "credits": 1 }]
}
```

## 4. Track delivery

- **Webhook (recommended):** register a URL and receive `message.delivered` / `message.failed` in real time — see [Webhooks](https://smsprovider-web.vercel.app/docs/webhooks).
- **Polling:** `GET https://smsprovider-web.vercel.app/api/v1/messages/{id}`.

Message lifecycle: `queued` → `sent` → `delivered` / `failed` / `expired`. A cancelled scheduled message becomes `cancelled` and its credits are released.

## Important rules

- **Idempotency-Key** is required on every send POST. The same key within 24 hours returns the same response without charging twice — safe to retry after a timeout.
- Phones are accepted as `05XXXXXXXX`, `5XXXXXXXX`, `+972…` or `972…` and always returned in E.164.
- A delivery failure (handset off, number does not exist) does not refund the credit; a failure before sending releases it.