API

REST API referansı

Tüm endpoint'ler, parametreler, örnek istekler ve yanıtlar. Authentication: API key (Bearer).

Hızlı örnek

curl https://api.sendnomi.com.tr/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "[email protected]",
    "to": "[email protected]",
    "subject": "Hoş geldiniz",
    "html": "<h1>Merhaba!</h1>"
  }'

API key panel → Geliştirici sekmesinden alınır. Production ve test ortamı için ayrı, scope'lu key önerilir.

Kimlik doğrulama

Her istek Authorization: Bearer YOUR_API_KEY başlığı taşır. Key panel'de oluşturulur, oluşturma anında bir kez gösterilir, sonra hash'lenir. Kayıp ettiğinizde yeni key üretir, eskisini iptal edersiniz — eski key revoke edildiği anda devre dışı.

  • Scope tabanlı yetki: 30 scope (send · campaign · template · webhook · domain · ...). Bir key sadece izin verdiğiniz alanları kullanır.
  • IP allowlist: Production key'lerini belirli IP/CIDR aralıklarına kısıtlayabilirsiniz.
  • Süre limiti: Key'lere TTL atayabilirsiniz; süre dolunca otomatik geçersiz.
  • Audit log: Her key kullanımı timestamp + endpoint + sonuç kaydıyla loglanır.

Idempotency-Key

POST isteklerinde Idempotency-Key başlığı kullanın — aynı key ile gelen ikinci istek, ilk yanıtı tekrar döner ve mükerrer gönderim olmaz. UUIDv4 önerilir; key 24 saat saklanır. 

curl https://api.sendnomi.com.tr/v1/messages \
  -H "Authorization: Bearer sn_live_•••" \
  -H "Idempotency-Key: a1b2c3d4-e5f6-7890-..." \
  ...

Hata formatı

Tüm hata yanıtları aynı zarfla döner — kod + mesaj + isteğe-özel detay:

{
  "error": {
    "code":    "invalid_recipient",
    "message": "Alıcı adresi format kuralına uymuyor",
    "field":   "to",
    "request_id": "req_01HX8K..."
  }
}

HTTP durum kodları RFC 7231 uyumlu. Geçici hatalar 5xx + retry-after; kalıcı 4xx retry'a tabi değil.

Rate limit

Sınır planınıza bağlıdır; panel'de gerçek zamanlı görüntülenir. Her yanıt başlıklarında:

  • X-RateLimit-Limit · pencerede izin verilen istek sayısı
  • X-RateLimit-Remaining · kalan istek hakkı
  • X-RateLimit-Reset · pencerenin sıfırlandığı zaman (Unix epoch)

429 alırsanız Retry-After başlığındaki süreyi bekleyin. SDK'lar bunu otomatik yapar.

Sürümleme

URL'de sürüm zorunlu (/v1/). Yeni sürüme geçişte 12 ay deprecation penceresi + changelog uyarısı. Breaking change'ler asla sessiz değişmez — eski endpoint kullanılır kullanılmaz uyarı header'ı döner.

Endpoint listesi

  • POST /v1/messages Tekil veya toplu e-posta gönder.
  • GET /v1/messages/{id} Belirli bir gönderinin durumunu sorgula.
  • GET /v1/messages Gönderi listesi, filtreleme ve sayfalama desteği ile.
  • POST /v1/templates Yeni şablon oluştur (Handlebars + Liquid karması).
  • GET /v1/templates/{id} Şablon detay.
  • POST /v1/suppressions Suppression listesine adres ekle.
  • GET /v1/suppressions Suppression listesi.
  • POST /v1/webhooks Webhook endpoint kaydı.
  • GET /v1/events Olay akışı (sent, delivered, opened, clicked, bounced, complained).
  • GET /v1/domains Doğrulanmış alan adlarınız.

OpenAPI 3.1 spec: /v1/openapi.json — IDE / Postman içeri aktarma için. Her endpoint'in tam parametre + örnek istek + yanıt şeması belgeli.