---
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-05-05
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`) |

## Rate limits

The `send-sms` endpoint supports two distinct usage patterns, each with its own limit:

- **Transactional sending:** up to **100 SMS per second** per account. For per-user, latency-sensitive messages such as OTP, login codes, order/delivery notifications, and appointment reminders. One request per trigger; typically one recipient per request. The cap counts SMS (recipients), not requests, a 5-recipient request counts as 5 SMS, so if you batch 5 recipients per call, target at most 20 requests per second.
- **Bulk sending:** up to **50,000 recipients in a single request** (`order.message.receipents.number` array). For campaigns, broadcasts, and mass alerts. One `orderId` per request; pull delivery reports via [`get-report`](./get-report.md).

For larger workloads:

- For recipient lists over 50,000, chunk client-side at `chunkSize=50000` and issue sequential `send-sms` calls; each call returns its own `orderId`.
- For sustained throughput above 100 transactional SMS per second, plan ahead with `destek@emarka.com.tr` so dedicated capacity can be provisioned.
- Use exponential backoff in production error paths; abnormal traffic may be temporarily throttled to protect overall service health.

## 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), scheduled send time, format "dd/MM/yyyy HH:mm" (Turkey local time)
   └─ message
      ├─ text (string, required), SMS body
      └─ receipents
         └─ number (string[], required), accepts 905XXXXXXXXX, +905XXXXXXXXX, 5XXXXXXXXX
```

> The `iys` field is always required. **Decision rule:** if the message's purpose is to market a product or service, send `"1"` (campaign, promotion, discount, greeting, survey). For everything else send `"0"` (OTP, login code, password reset, order/delivery/payment notification, appointment reminder, account update, regulatory notice). Transactional messages fall outside the scope of commercial-message consent under Law No. 6563 (Turkish E-Commerce Law) and İYS rules; no prior consent is required ([iys.org.tr/sss](https://iys.org.tr/iys/sss)) and `iysList` is then ignored. Personal-data obligations under KVKK (Law No. 6698) continue to apply separately. Commercial messages require `iysList` (`BIREYSEL` for individuals, `TACIR` for businesses); skipping it may trigger legal penalties. **When sender is `"APITEST"`, `iys` must be `"0"`** (test mode replaces the message body with a fixed verification text).

> **Field name spelling:** the field is intentionally named `receipents` (sic.) for backward compatibility. **The spelling `recipients` does not work** and is not auto-corrected; sending `recipients` produces an empty recipient list and returns `452`. The field also sits **inside `message`**, not directly under `order`, legacy examples placing it as `order.receipents` are wrong; the correct path is `order.message.receipents`.

> **Legal responsibility.** Some API versions accept the request with a 200 response and dispatch the message even when `iys` and `iysList` are missing. That tolerance is a backend behaviour, not a waiver of the legal obligation. **Always** send `iys: "1"` and the correct `iysList` (`BIREYSEL` or `TACIR`) for commercial content, the backend performs a real-time İYS check and drops non-consented recipients. Sending commercial SMS without these fields exposes you to per-recipient administrative fines under Law No. 6563; the responsibility lies with the sender.

### 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.

#### 466: Hatalı numara ("Invalid number")

One or more numbers in `receipents.number` are outside the accepted format (Turkish operator prefix `5XX` missing or wrong digit count). Accepted formats: `905XXXXXXXXX`, `+905XXXXXXXXX`, `5XXXXXXXXX`. For non-Turkish numbers, enable International mode in the panel.

#### Other error codes

For the full table of `400, 402, 450, 453, 454, 457, 466, 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. **One-line decision rule:** if the message markets a product or service, send `"1"` + `iysList`; everything else (OTP, notification, reminder, account event, regulatory notice) is `"0"`. Transactional messages are not commercial-electronic-messages under Law No. 6563 (Turkish E-Commerce Law); no prior commercial consent is required. KVKK personal-data obligations apply separately. When using sender `"APITEST"`, `iys` must be `"0"`.
- **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)