---
title: "Send SMS API (send-sms)"
description: "Use the send-sms endpoint to deliver an SMS to one or many mobile numbers in a single request. Sender ID, IYS flag, message text, and recipient list."
slug: /en/docs/api/send-sms
locale: en
audience: developer
last_updated: 2026-04-29
endpoint:
  method: POST
  path: /v1/send-sms/json
  base_url: https://api.iletimerkezi.com
auth: api-key-and-hash
related: [authentication, get-report, get-sender, get-balance, error-codes]
alternates:
  tr: https://www.iletimerkezi.com/docs/api/send-sms
  en: https://www.iletimerkezi.com/en/docs/api/send-sms
  toplusmsapi: https://toplusmsapi.com/sms/gonder/json
  a2psmsapi: https://a2psmsapi.com/en/sms/gonder/json
---

# Send SMS API (send-sms)

The `send-sms` endpoint delivers an SMS to one or many mobile numbers in a single request. Each request is treated as an **order**; the response returns an `orderId` you can use to retrieve delivery reports or cancel scheduled orders. One order per request, one sender (header) per order.

## Prerequisite: enable API access in the panel

> Before calling this endpoint, the **Allow API access** toggle must be on in your iletiMerkezi panel.
>
> Location: `panel.iletimerkezi.com` → **Settings → Security → Access Permissions**
>
> If it is off, every request returns `401 — Üyelik bilgileri hatalı` ("Authentication failed"). See [authentication.md](./authentication.md) for details.

## Endpoint

| Field | Value |
|---|---|
| Method | `POST` |
| URL | `https://api.iletimerkezi.com/v1/send-sms/json` |
| Content-Type | `application/json` |
| Auth | API Key + Hash (`request.authentication`) |

## Request

### Schema

```
request
├─ authentication
│  ├─ key (string, required)
│  └─ hash (string, required)
└─ order
   ├─ sender (string, required)         — sender ID approved in panel, max 11 chars
   ├─ iys (string, required)             — "1" or "0"
   ├─ iysList (string, conditional)      — if iys=1, "BIREYSEL" or "TACIR"
   ├─ sendDateTime (string[], optional)  — future schedule, format "DD/MM/YYYY HH:MM"
   └─ message
      ├─ text (string, required)         — SMS body
      └─ receipents
         └─ number (string[], required)  — accepts 905XXXXXXXXX, +905XXXXXXXXX, 5XXXXXXXXX
```

> The `iys` field is always required. For commercial messages (campaigns, promotions, greetings) send `"1"` along with a valid `iysList` (`BIREYSEL` for individuals, `TACIR` for businesses); failure to do so may trigger legal penalties under Turkish regulation. For transactional messages (notifications, OTP, delivery, regulatory), send `"0"`; `iysList` is then ignored.

> The `receipents` (sic.) field sits **inside `message`**, not directly under `order`. Some legacy examples place it as `order.receipents` — that is incorrect; the correct path is `order.message.receipents`.

### Full example

```json
{
  "request": {
    "authentication": {
      "key": "API_KEY",
      "hash": "API_HASH"
    },
    "order": {
      "sender": "YOURBRAND",
      "iys": "0",
      "message": {
        "text": "Order #1234 prepared and shipped.",
        "receipents": {
          "number": ["905XXXXXXXXX"]
        }
      }
    }
  }
}
```

For multiple recipients, add to the same `number` array:

```json
"receipents": {
  "number": ["905XXXXXXXXX", "905YYYYYYYYY", "905ZZZZZZZZZ"]
}
```

## Response

### Success (200)

```json
{
  "response": {
    "status": {
      "code": 200,
      "message": "İşlem başarılı"
    },
    "order": {
      "id": "312891245"
    }
  }
}
```

`İşlem başarılı` means "Request successful" in Turkish.

**Fields:**

- `response.status.code` (integer): internal status code, mirrors the HTTP code
- `response.status.message` (string): human-readable Turkish message
- `response.order.id` (string): unique numeric order ID. Use it with [`get-report`](./get-report.md) to fetch delivery reports, or to cancel a scheduled order.

### Error responses

#### 401 — Üyelik bilgileri hatalı ("Authentication failed")

API Key / Hash invalid, or the panel toggle is off. See [authentication.md](./authentication.md).

#### 451 — Tekrar eden sipariş ("Duplicate order")

The same `sender + recipient + text` was sent again within a short window (idempotency guard). Vary the message text or check the previous order's status with [`get-report`](./get-report.md) before retrying.

#### 452 — Mesaj alıcıları hatalı ("Invalid recipients")

`receipents.number` is empty, malformed, or the field is missing. The most common cause: `receipents` placed directly under `order` instead of under `order.message`. Check the path first.

#### Other error codes

For the full table of `400, 402, 450, 453, 454, 457, 468, 469, 470`: see [error-codes.md](./error-codes.md).

## Code samples

### cURL

```bash
curl -X POST 'https://api.iletimerkezi.com/v1/send-sms/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "request": {
      "authentication": {
        "key": "'"$ILETIMERKEZI_API_KEY"'",
        "hash": "'"$ILETIMERKEZI_API_HASH"'"
      },
      "order": {
        "sender": "YOURBRAND",
        "iys": "0",
        "message": {
          "text": "Order prepared and shipped.",
          "receipents": { "number": ["905XXXXXXXXX"] }
        }
      }
    }
  }'
```


## Common pitfalls

- **Misplacing `receipents`.** The correct path is `order.message.receipents.number[]`, not `order.receipents`. Legacy examples may show the wrong nesting; if you hit a `452`, check this first.
- **`iys` is required, with no default.** Skip it and the request fails. Commercial messages must use `"1"` plus a valid `iysList`; otherwise legal action under Turkish IYS regulations is possible.
- **Sender must be approved in the panel.** Sender IDs like `YOURBRAND` need panel approval before they can be used. Pull the approved list with [`get-sender`](./get-sender.md). While approval is pending, you can set the sender to `"APITEST"` to test the HTTP integration (the message body is replaced with a fixed test text, but the full request/response/report flow runs). See [test-mode](./test-mode.md).
- **Watch for duplicate orders.** Sending the same `sender + recipient + text` in quick succession returns `451`. For idempotent calls, append a unique reference (order ID, timestamp) to the text.
- **Number format is flexible but stay consistent.** `905XXXXXXXXX`, `+905XXXXXXXXX`, and `5XXXXXXXXX` are all accepted. Pick one (preferably `905XXXXXXXXX`, 12 digits) for easier debugging.
- **International numbers require abroad mode.** To send to country codes outside Turkey (`+49`, `+44`, etc.), enable abroad mode under **Settings → SMS → Abroad** in the panel. Activation converts your credit balance to a TL balance and the account stays in TL mode. See [overview](./overview.md).
- **Compare balance before and after.** Use [`get-balance`](./get-balance.md) on each side of a test send. Message length (eMarka limits, lower than standard SMS due to the B186 prefix: English 155/153, Turkish 150/148, Unicode 65/63), character mode, scheduled orders, and multi-part splits all affect credit consumption. See [overview](./overview.md).
- **Up to 7 parts / ~1071 characters.** A single message cannot exceed 7 concatenated parts. Longer content must be shortened or split via an iim.to short link.
- **Undelivered SMS are free.** Messages that fail to reach the recipient (off network, invalid number, blacklist) do not consume credit. Read actual consumption from [`get-report`](./get-report.md) — the `delivered` counter and `price` field.
- **11-character sender limit.** Maximum 11 alphanumeric characters; spaces count.
- **Save characters with short links.** Pasting long URLs in the body burns through the first-SMS limit (155 / 150 / 65 depending on character set) fast. Create an `iim.to/...` short link in the iletiMerkezi panel and paste it instead — click tracking and the auto opt-out flow run through this link. Short links are managed in the panel today; there is no separate API endpoint.


## Related

- [Authentication](./authentication.md)
- [Approved sender IDs (get-sender)](./get-sender.md)
- [Delivery report (get-report)](./get-report.md)
- [Get balance](./get-balance.md)
- [Error code table](./error-codes.md)