--- title: "SMS Gönderme API (send-sms)" description: "send-sms endpoint'i ile tek seferde tek veya çoklu numaraya SMS gönderirsiniz. Sender ID, İYS bayrağı, mesaj metni ve alıcı listesi ile çalışır." slug: /docs/api/send-sms locale: tr 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 --- # SMS Gönderme API (send-sms) `send-sms` endpoint'i tek bir istekle bir veya birden çok cep telefonuna SMS gönderir. İstek bir **sipariş (order)** olarak kabul edilir; başarılı yanıtta dönen `orderId` ile teslimat raporlarını takip edebilir, ileri tarihli siparişleri iptal edebilirsiniz. İstek başına yalnızca bir sipariş, sipariş başına bir sender (başlık) gönderilir. ## Önemli ön koşul: Panel'de API erişimi > Bu endpoint'i çağırmadan önce panelinizde **API kullanımına izin ver** seçeneğinin aktif olması gerekir. > > Ayar yeri: `panel.iletimerkezi.com` > **Ayarlar > Güvenlik > Erişim İzinleri** > > Aktif değilse istek `401: Üyelik bilgileri hatalı` ile döner. Detay: [authentication.md](./authentication.md) ## Endpoint | Alan | Değer | |---|---| | Method | `POST` | | URL | `https://api.iletimerkezi.com/v1/send-sms/json` | | Content-Type | `application/json` | | Auth | API Key + Hash (`request.authentication`) | ## Hız sınırları `send-sms` endpoint'i iki farklı kullanım pattern'ini destekler ve her birinin ayrı bir sınırı vardır: - **Anlık (transactional) gönderim:** Hesap bazında **saniyede 100 SMS**'e kadar. OTP, giriş kodu, sipariş/teslimat bildirimi, randevu hatırlatma gibi kullanıcı başına tetiklenen ve gecikmeye duyarlı mesajlar için. Her tetiklemede ayrı istek atın; istek başına genellikle 1 alıcı. Sınır toplam SMS sayısı (alıcı) üzerindendir, istek sayısı değil: 5 alıcılı bir istek 5 SMS sayılır, dolayısıyla 5 alıcılı istek atıyorsanız saniyede en fazla 20 istek hedefleyin. - **Toplu (bulk) gönderim:** Tek istekte **50.000 alıcıya** kadar (`order.message.receipents.number` dizisi). Kampanya, duyuru, kitle bildirimi için. Tek `orderId` altında tek sipariş açılır; teslimat raporu [`get-report`](./get-report.md) ile alınır. Daha büyük hacim gerekiyorsa: - 50.000'in üzerindeki alıcı listelerini istemcide parçalayın (`chunkSize=50000`) ve ardışık `send-sms` çağrıları yapın; her çağrı ayrı bir `orderId` üretir. - Sürekli olarak saniyede 100 transactional SMS'i aşan ihtiyaçlar için entegrasyonu önceden `destek@emarka.com.tr` ile planlayın; özel kapasite tahsis edilebilir. - Üretim hata akışlarında exponential backoff kullanın; servis sağlığını korumak amacıyla anormal trafik geçici kısıtlanabilir. ## Request ### Şema ``` request ├─ authentication │ ├─ key (string, zorunlu) │ └─ hash (string, zorunlu) └─ order ├─ sender (string, zorunlu), panelde onaylı sender ID, max 11 karakter ├─ iys (string, zorunlu), "1" veya "0" ├─ iysList (string, koşullu), iys=1 ise "BIREYSEL" veya "TACIR" ├─ sendDateTime (string, opsiyonel), ileri tarihli gönderim zamanı, format "dd/MM/yyyy HH:mm" (Türkiye yerel saati) └─ message ├─ text (string, zorunlu), SMS metni └─ receipents └─ number (string[], zorunlu), 905xxxxxxxxx, +905xxxxxxxxx, 5xxxxxxxxx kabul edilir ``` > `iys` alanı her zaman zorunludur. **Karar kuralı:** mesajın amacı bir ürün veya hizmeti pazarlamak ise `"1"` (kampanya, promosyon, indirim, tebrik, anket); diğer her şey `"0"` (OTP, giriş kodu, şifre sıfırlama, sipariş/teslimat/ödeme bildirimi, randevu hatırlatma, hesap güncelleme, mevzuat tebliği). Transactional mesajlar 6563 sayılı Elektronik Ticaretin Düzenlenmesi Hakkında Kanun ve İYS uygulama kuralları çerçevesinde ticari elektronik ileti kapsamı dışındadır; önceden onay aranmaz ([iys.org.tr/sss](https://iys.org.tr/iys/sss)) ve `iysList` o durumda yok sayılır. KVKK kapsamındaki kişisel veri işleme yükümlülükleri ayrıca devam eder. Ticari mesajlarda `iysList` zorunlu (`BIREYSEL` veya `TACIR`); aksi halde yasal yaptırım söz konusudur. **Sender `"APITEST"` ise `iys` her zaman `"0"`** (test mode, mesaj metni sabit doğrulama metniyle değiştirilir). > **Alan adı yazımı:** Alan adı API'de geriye dönük uyumluluk için `receipents` (sic.) olarak korunur. **`recipients` yazımı çalışmaz**, otomatik düzeltilmez; doğru yazım `recipients` sanılarak gönderilirse alıcı listesi okunamaz ve `452` döner. Ayrıca alan **`message` altındadır**, `order` altında değil, eski örneklerde `order.receipents` görülebilir, doğrusu `order.message.receipents`'tir. > **Yasal sorumluluk:** API'nın bazı sürümlerinde `iys` ve `iysList` alanları gönderilmediğinde de istek 200 ile sonuçlanıp mesaj iletilebiliyor. Bu API tarafındaki bir tolerans; yasal yükümlülüğü kaldırmaz. Ticari içerik gönderirken `iys: "1"` ve uygun `iysList` (`BIREYSEL` veya `TACIR`) değerini **her durumda** gönderin, backend gerçek-zamanlı İYS sorgusu yapar ve izinsiz alıcıları düşürür. Bu alanları atlayarak ticari SMS göndermek 6563 sayılı kanun kapsamında alıcı başına idari para cezasına yol açar; sorumluluk send eden taraftadır. ### Tam örnek ```json { "request": { "authentication": { "key": "API_KEY", "hash": "API_HASH" }, "order": { "sender": "BASLIGINIZ", "iys": "0", "message": { "text": "Sipariş #1234 hazırlandı, kargoya verildi.", "receipents": { "number": ["905XXXXXXXXX"] } } } } } ``` Birden fazla alıcı için aynı `number` dizisine ekleyin: ```json "receipents": { "number": ["905XXXXXXXXX", "905YYYYYYYYY", "905ZZZZZZZZZ"] } ``` ## Response ### Başarılı (200) ```json { "response": { "status": { "code": 200, "message": "İşlem başarılı" }, "order": { "id": "312891245" } } } ``` **Alanlar:** - `response.status.code` (integer): HTTP durum koduna paralel iç durum kodu - `response.status.message` (string): Türkçe açıklama - `response.order.id` (string): Siparişe atanan eşsiz numerik ID. Teslimat raporu ([`get-report`](./get-report.md)) ve ileri tarih siparişlerinin iptali için bu ID kullanılır. ### Hata yanıtları #### 401: Üyelik bilgileri hatalı API Anahtar/Hash doğrulanamadı veya panel toggle kapalı. Detay: [authentication.md](./authentication.md). #### 451: Tekrar eden sipariş Aynı sender + alıcı + mesaj metni kombinasyonu kısa süre içinde yeniden gönderildi (idempotency koruması). Mesaj metnini değiştirin veya bir önceki siparişin durumunu [`get-report`](./get-report.md) ile kontrol edin. #### 452: Mesaj alıcıları hatalı `receipents.number` boş, geçersiz formatta veya alanı tamamen eksik. En yaygın sebep: `receipents`'in yanlış yere (`order.receipents` gibi) yerleştirilmiş olması. Doğru konum: `order.message.receipents`. #### 466: Hatalı numara `receipents.number` içindeki bir veya daha fazla numara geçerli format dışında (Türkiye operatör prefix'i `5XX` değil veya hane sayısı uyumsuz). Numara format'ları: `905XXXXXXXXX`, `+905XXXXXXXXX`, `5XXXXXXXXX`. Yurt dışı numara için panelden Yurt Dışı modunu aktive edin. #### Diğer hata kodları `400, 402, 450, 453, 454, 457, 466, 468, 469, 470` kodları için tam tablo: [error-codes.md](./error-codes.md). ## Kod örnekleri ### 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": "BASLIGINIZ", "iys": "0", "message": { "text": "Sipariş hazırlandı, kargoya verildi.", "receipents": { "number": ["905XXXXXXXXX"] } } } } }' ``` ## Common Pitfalls - **`receipents` yerini şaşırma.** Pattern `order.message.receipents.number[]`'dir, `order.receipents` değil. Eski örneklerde yanlış yer görülür; 452 alıyorsanız ilk kontrol edilecek nokta budur. - **`iys` zorunlu, default'u yok.** Alanı atlarsanız istek geçmez. **Karar kuralı tek cümle:** mesajın amacı ürün/hizmet pazarlamak ise `"1"` + `iysList`; diğer her şey (OTP, bildirim, hatırlatma, hesap işlemi, mevzuat tebliği) `"0"`. Transactional mesajlar 6563 sayılı Elektronik Ticaret Kanunu kapsamında ticari ileti sayılmaz; önceden ticari onay aranmaz. KVKK kişisel veri yükümlülükleri ayrıca devam eder. `APITEST` sender kullanıyorsan iys = `"0"` zorunlu. - **Sender panelde onaylı olmalı.** `eMarka Test` gibi başlıklar panel onayı gerektirir; onaylı listeyi [`get-sender`](./get-sender.md) endpoint'i ile çekebilirsiniz. Onayı beklerken sender değerini `"APITEST"` yaparak HTTP entegrasyonunu test edebilirsiniz (mesaj metni sabit bir test metniyle değiştirilir, akış tam çalışır). Detay: [test-mode](./test-mode.md). - **Tekrar eden siparişe dikkat.** Aynı `sender + numara + text` kısa zaman aralığında gönderilirse `451` döner. İdempotent kullanımda mesaj sonuna unique bir referans (sipariş ID, timestamp) ekleyin. - **Numara formatı esnek ama tutarlı kullanın.** `905XXXXXXXXX`, `+905XXXXXXXXX`, `5XXXXXXXXX` kabul edilir. Tek bir formatta kalmak hata ayıklamayı kolaylaştırır; tercihen `905XXXXXXXXX` (12 hane). - **Yurt dışı numara için yurt dışı modu gerekir.** Türkiye dışı country code (`+49`, `+44` vb.) ile gönderim yapmak için panelden **Ayarlar > SMS > Yurt Dışı** modunu aktifleştirin. Aktivasyon kontör bakiyesini TL bakiyeye çevirir; sonra bu modda kalırsınız. Detay: [overview](./overview.md). - **Bakiyeyi öncesi/sonrası karşılaştırın.** Test ortamında [`get-balance`](./get-balance.md) ile her gönderim öncesi ve sonrası bakiyeyi loglayın. Mesaj uzunluğu (eMarka karakter limitleri B186 prefix sebebiyle: İngilizce 155/153, Türkçe 150/148, Unicode 65/63), karakter modu (`sendDateTime` ile ileri tarihli sipariş, çok-parçalı mesaj) gibi etkenler kontör tüketimini etkiler. Detay: [overview](./overview.md). - **Maksimum 7 parça / ~1071 karakter.** Tek mesaj 7 parçayı geçemez. Daha uzun içerik ya kısaltılmalı ya da iim.to kısa link ile dağıtılmalı. - **Teslim edilmeyen SMS ücretsizdir.** Kapalı hat, geçersiz numara veya kara liste sebebiyle teslim edilmeyen mesajlar için kontör harcanmaz. [`get-report`](./get-report.md) `delivered` ve `price` alanlarından gerçek tüketim okunur. - **Sender ID 11 karakter sınırı.** Maksimum 11 karakter; alfanumerik. Boşluk hesaba katılır. - **Mesaj metni karakter ekonomisi.** Uzun URL'leri ham olarak yapıştırırsanız ilk SMS karakter sınırına (155 / 150 / 65) hızla çarparsınız. iletiMerkezi panelinden `iim.to/...` kısa linki oluşturup mesaja yapıştırın; tıklama raporları ve otomatik çıkış (opt-out) akışı da bu link üzerinden işler. Kısa link şu an panelden yönetilir, ayrı API endpoint'i yoktur. ## Related - [Kimlik doğrulama (authentication)](./authentication.md) - [Onaylı sender ID listesi (get-sender)](./get-sender.md) - [Teslimat raporu (get-report)](./get-report.md) - [Bakiye sorgulama (get-balance)](./get-balance.md) - [Hata kodları tablosu](./error-codes.md)