Ana içeriğe geç

SMS gönderme

POST 
/send

İstek: POST https://ext-api.netgsm.com.tr/sms/v3/send
Canlı ortam: https://ext-api.netgsm.com.tr/sms/v3

Bir ya da daha fazla alıcıya SMS gönderen bir görev oluşturur. Görev iletim için kabul edildiğinde 202 döner; iletim sonradan yapılır. Her alıcı messages dizisinde ayrı bir kayıttır ve her kaydın kendi metni olabilir.

Kayıt başına doğrulama. Hatalı kayıtlar toplu gönderimi başarısız kılmaz: geçerli kayıtlar gönderilir, hatalılar yanıttaki rejectedItems içinde konumları (index) ve nedenleriyle bildirilir. Kayıtların hepsi hatalıysa görev oluşturulmaz ve 422 NO_DELIVERABLE_MESSAGES döner; bu yanıt da reddedilen kayıtları aynı biçimde rejectedItems ve rejectedItemsTruncated alanlarında taşır.

İstek biçimi. Content-Type: application/json; gövde sıkıştırılmamış olmalı ve 500 MB'ı aşmamalıdır. Bilinmeyen alanlar yok sayılır; null verilen bir alan hiç verilmemiş sayılır.

İstek sınırı. Hesap başına dakikada 50.000 istek (mesaj değil, istek). Süre penceresi ilk istekle başlar ve sabittir; reddedilen istekler sayılmaz. Aşıldığında 429 Retry-After başlığıyla döner. Toplu gönderimler için çok sayıda alıcıyı tek istekte göndermenizi öneririz.

Yeniden deneme. İsteklerin tekilleştirilmesi yoktur: aynı istek iki kez gönderilirse iki görev oluşur. 503 SERVICE_UNAVAILABLE çoğunlukla hiçbir şeyin kuyruğa alınmadığını gösterir. Toplu gönderimi körlemesine yeniden göndermeden önce GET /report ile kontrol edebilirsiniz. 400, 403, 413 ve 422 yanıtları aynı istekle tekrarlandığında yine aynı sonucu verir.

Sonrası. Yanıttaki jobId ile iletim raporlarını GET /report, gönderim istatistiklerini GET /stats ile sorgulayabilirsiniz. status SCHEDULED olan bir görev, başlangıç zamanına kadar POST /cancel ile iptal edebilirsiniz.

Request​

Bodyrequired

    senderstringrequired

    Gönderici başlığı. Hesaba kayıtlı bir başlıkla yazıldığı gibi birebir eşleşmelidir: büyük/küçük harf dahil, kırpma yapılmaz. Alfanümerik bir başlık (örneğin NETGSM) ya da hesabın abone numarası olabilir; abone numarası başında 0 ya da 90 olmadan yazılır (5061234567). Kullanabileceğiniz başlıkları ve her birinin kullanılabilir olup olmadığını GET /senders ile görebilirsiniz. Eşleşmezse istek 422 REJECTED_HEADER ile reddedilir; boş ya da yalnızca boşluktan oluşan bir değer ise 400 ile reddedilir.

    Possible values: non-empty and <= 35 characters

    Example: NETGSM
    messages object[]required

    Gönderilecek mesajlar; her alıcı için bir kayıt. En az 1, en fazla 1.000.000 kayıt; fazlası 400 ile reddedilir.

    Possible values: >= 1, <= 1000000

  • Array [
    • textstringrequired

    Mesaj metni. Boş olamaz (INVALID_MESSAGE). En fazla uzunluk encoding değerine ve göndericinin türüne bağlıdır (MESSAGE_TOO_LONG); bkz. encoding ve /length.

    Example: Siparişiniz kargoya verildi.
    recipientstringrequired

    Alıcı numarası, iki biçimden biriyle yazılır; yalnızca rakamlar ve yurt dışı için baştaki tek - kullanılabilir, boşluk, parantez ya da tire ayracı olmaz:

    TürBiçimÖrnek
    Türkiye90 ve ardından 10 rakam; + ya da baştaki 0 olmadan+90 506 123 45 67 için 905061234567
    Yurt dışı- ve ardından ülke koduyla birlikte 9–17 rakam; + ya da 00 olmadan+49 151 12345678 için -4915112345678

    Yanlış yazımlar: +905061234567, 05061234567, 5061234567, 0049151…, -+49151…. Bu biçimlere uymayan kayıt INVALID_RECIPIENT ile reddedilir. Numaranın gerçekte var olup olmadığı ya da hangi operatöre ait olduğu burada denetlenmez; iletim sonucunu GET /report ile görebilirsiniz. Hesabın yurt dışı gönderim izni yoksa yurt dışı kayıtlar NO_INTERNATIONAL_PERMISSION ile reddedilir.

    Possible values: Value must match regular expression ^(90\d{10}|-\d{9,17})$

    Example: 905061234567
  • ]
    • encodingstring

    Metnin karakter kodlaması. Tüm kayıtlara uygulanır. Büyük/küçük harfe duyarlıdır; listede olmayan bir değer (turkish, GSM dahil) istek 400 1 field(s) rejected ile reddedilir; violations alanı (encoding) ve geçerli değerleri belirtir.

    DeğerNe zamanEn fazla uzunluk
    DEFAULTStandart GSM alfabesi. Türkçe karakterler Latin karşılıklarına çevrilir (ç→c, ş→s gibi).917
    TURKISHTürkçe karakterlerin (çğıöşüÇĞİÖŞÜ) korunması gerektiğinde. çğışĞİŞ iki karakter sayılır.888
    UNICODEEmoji ya da Arapça, Kiril gibi GSM alfabesinde olmayan karakterler için.396

    Alfanümerik bir gönderici başlığında her sınır 5 karakter azdır. Sınırı aşan kayıt MESSAGE_TOO_LONG ile reddedilir. Bir metnin kaç SMS'e bölüneceğini POST /length ile hesaplayabilirsiniz.

    Possible values: [DEFAULT, TURKISH, UNICODE]

    Default value: DEFAULT
    iysFilterstring

    İYS (İleti Yönetim Sistemi) izin filtresi; ticari iletilerde alıcının izni olmayanlar gönderimden çıkarılır. Büyük/küçük harf fark etmez:

    DeğerAnlamı
    NONEFiltre yok. Yalnızca bilgilendirme (ticari olmayan) iletiler için.
    BRANDMarka adına alınmış izinlere göre filtrelenir.
    RETAILERBayi adına alınmış izinlere göre filtrelenir.
    BRAND_AND_RETAILERHer ikisine göre filtrelenir.

    Bunların dışındaki her değer NONE sayılır. Hesap ticari gönderim (marka ya da bayi) tipinde tanımlıysa istekteki değer yok sayılır ve hesabın tipi uygulanır.

    BRAND ya da RETAILER uygulanacaksa göndericinin İYS marka kodu olmalıdır; hesap İYS modunda değilse bu iki değer istek 422 REJECTED_IYS ile reddedilir. BRAND_AND_RETAILER için bu iki kontrol yapılmaz.

    Possible values: [NONE, BRAND, RETAILER, BRAND_AND_RETAILER]

    Default value: NONE
    startAtdate-time

    En erken gönderim zamanı, saat dilimi farkıyla (2026-09-10T09:00:00+03:00). Verilmezse ya da geçmişteyse gönderim hemen başlar. 18 aydan daha ilerisi 400 INVALID_SEND_WINDOW ile reddedilir. Bir dakikadan daha ileri bir başlangıç görevi SCHEDULED yapar. Saat dilimi farkı olmayan ya da okunamayan bir tarih istek 400 ile reddedilir.

    stopAtdate-time

    En geç gönderim zamanı, saat dilimi farkıyla. Verilmezse ya da geçmişteyse startAt + 21 saat kabul edilir. Aralık, 1000 ve üzeri mesajda 10 dakikadan, daha azında 5 dakikadan kısaysa bu süreye uzatılır; 21 saatten uzunsa 21 saate kısaltılır. Bu düzeltmeler hata döndürmez ve belirlenen aralık yanıtta yer almaz.

    partnerCodestring

    İş ortağı (bayi) kodu. Yalnızca kayıt amaçlıdır; gönderimi etkilemez.

    Possible values: <= 32 characters

    referenceIdstring

    Yanıtta aynen geri döndürülür.

    Possible values: <= 50 characters

    appNamestring

    Gönderimi yapan uygulamanın adı. Yalnızca kayıt amaçlıdır; gönderimi etkilemez.

    Possible values: <= 50 characters

Responses​

Görev oluşturuldu. İletim sonradan yapılır.

Schema
    jobIdstringrequired

    Oluşturulan görevin numarası. Rapor, istatistik ve iptal için kullanılır; destek taleplerinde belirtmelisiniz.

    statusstringrequired
    DeğerAnlamı
    QUEUEDGönderim hemen başladı; görev iptal edilemez.
    SCHEDULEDGörev startAt zamanına kadar bekletiliyor (dakikaya göre bir dakikadan daha ileri bir başlangıç); o zamana kadar POST /cancel ile iptal edebilirsiniz.

    Possible values: [QUEUED, SCHEDULED]

    acceptedintegerrequired

    Gönderime alınan kayıt sayısı. accepted + rejected, istekteki kayıt sayısına eşittir.

    rejectedintegerrequired

    Reddedilen kayıt sayısı. rejectedItems kısaltılsa da bu sayı tamdır.

    rejectedItems object[]required

    Reddedilen kayıtlar, index sırasıyla ilk 100 tanesi. Hiçbiri reddedilmediyse boş dizi.

    Possible values: <= 100

  • Array [
    • indexintegerrequired

    Kaydın istekteki messages dizisindeki sırası, sıfırdan başlar.

    recipientstringnullablerequired

    Kayıttaki alıcı. Kayıt null ise ya da alıcısı yoksa null.

    reasonstringrequired
    DeğerNe zaman
    INVALID_RECIPIENTNumara eksik ya da biçimi yanlış; bkz. recipient.
    INVALID_MESSAGEMetin eksik ya da boş.
    MESSAGE_TOO_LONGMetin, encoding ve gönderici türüne göre sınırı aşıyor; bkz. encoding.
    MALFORMED_ENTRYKayıt null.
    DUPLICATE_RECIPIENTAynı alıcı istekte daha sonra yeniden geçiyor. Yalnızca son geçen kayıt gönderilir, öncekiler bu nedenle reddedilir; son kayıt başka bir nedenle reddedilse bile. Numaralar yazıldığı gibi karşılaştırılır. Mükerrer gönderime izin verilen hesaplarda uygulanmaz.
    NO_INTERNATIONAL_PERMISSIONNumara yurt dışı (- ile başlıyor) ve hesabın yurt dışı gönderim izni yok. İzin için destek ekibiyle iletişime geçmelisiniz. Yalnızca başka bir hatası olmayan kayıtlarda bildirilir.

    Bir kayıt birden fazla nedenle hatalıysa tek neden bildirilir; öncelik: DUPLICATE_RECIPIENT, MALFORMED_ENTRY, MESSAGE_TOO_LONG, INVALID_RECIPIENT, INVALID_MESSAGE, NO_INTERNATIONAL_PERMISSION.

    Possible values: [INVALID_RECIPIENT, INVALID_MESSAGE, MESSAGE_TOO_LONG, MALFORMED_ENTRY, DUPLICATE_RECIPIENT, NO_INTERNATIONAL_PERMISSION]

  • ]
    • rejectedItemsTruncatedbooleanrequired

    100'den fazla kayıt reddedildiği için rejectedItems kısaltıldıysa true. accepted ve rejected yine tamdır.

    referenceIdstringnullablerequired

    İstekte verilen referenceId; verilmediyse null.

Örnek istek​

curl -X POST 'https://ext-api.netgsm.com.tr/sms/v3/send' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "sender": "NETGSM",
  "messages": [
    {
      "text": "Merhaba",
      "recipient": "905xxxxxxxxx"
    }
  ],
  "referenceId": "order-4711"
}'