Ana içeriğe geç

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

{
  "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:

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

Response

Success (200)

{
  "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 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.

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

Code samples

cURL

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. 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.
  • 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.
  • Compare balance before and after. Use get-balance 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.
  • 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 — 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

Last updated: 2026-04-29 · Türkçe