{
  "openapi": "3.0.3",
  "info": {
    "title": "SenderTR API",
    "version": "1.1.0",
    "description": "SenderTR işlemsel e-posta, doğrulama ve pazarlama API'si. Kimlik: X-Api-Key başlığı (panelden üretilen str_… anahtar) ya da gönderim hesabının API anahtarı. Tüm hatalar {error, message} zarfıyla döner; her yanıtta X-Request-Id başlığı vardır.",
    "contact": { "email": "destek@sendertr.com", "url": "https://docs.sendertr.com" }
  },
  "servers": [{ "url": "https://api.sendertr.com/v1" }],
  "security": [{ "ApiKey": [] }],
  "components": {
    "securitySchemes": { "ApiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" } },
    "parameters": {
      "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "Aynı anahtarla 24 saat içinde tekrarlanan istek aynı yanıtı döner, ikinci ileti oluşmaz. Farklı gövdeyle aynı anahtar 409 idempotency_key_reused." }
    },
    "schemas": {
      "Error": { "type": "object", "properties": { "error": { "type": "string", "example": "insufficient_credit" }, "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "retry_after": { "type": "integer" } }, "required": ["error", "message"] },
      "SendRequest": {
        "type": "object", "required": ["to", "subject"],
        "properties": {
          "to": { "type": "string", "format": "email" },
          "subject": { "type": "string", "maxLength": 500 },
          "html": { "type": "string" }, "text": { "type": "string" },
          "template": { "type": "string", "description": "Kayıtlı işlemsel şablon anahtarı; verildiğinde subject/html/text şablondan gelir (variables ile doldurulur)." },
          "variables": { "type": "object", "additionalProperties": { "type": "string" } },
          "from_email": { "type": "string", "format": "email" }, "from_name": { "type": "string" }, "reply_to": { "type": "string", "format": "email" },
          "cc": { "type": "array", "items": { "type": "string" } }, "bcc": { "type": "array", "items": { "type": "string" } },
          "attachments": { "type": "array", "items": { "type": "object", "properties": { "filename": { "type": "string" }, "content": { "type": "string", "format": "byte" }, "content_type": { "type": "string" } } } },
          "headers": { "type": "object" }, "tags": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object" },
          "track_opens": { "type": "boolean" }, "track_clicks": { "type": "boolean" },
          "priority": { "type": "string", "enum": ["normal", "critical"], "description": "critical yalnız izinli gönderim hesaplarında; aksi hâlde normal kabul edilir." },
          "expires_in": { "type": "integer", "minimum": 60, "maximum": 604800, "description": "İleti ömrü (sn). Varsayılan critical 900, normal 86400." },
          "send_at": { "type": "string", "format": "date-time", "description": "İleri tarihli gönderim (en çok 7 gün)." }
        }
      },
      "SendResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "id": { "type": "string", "example": "msg_01K6PZ3Q9E8W2V7XJ4N0B5C8RD" }, "message_id": { "type": "string" }, "status": { "type": "string", "example": "queued" }, "priority": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" } } },
      "MessageEvent": { "type": "object", "properties": { "event": { "type": "string", "enum": ["queued", "sent", "delivered", "deferred", "bounced", "expired", "failed", "cancelled", "opened", "clicked", "complained"] }, "at": { "type": "string", "format": "date-time" }, "detail": { "type": "string" }, "dsn_code": { "type": "string" }, "server": { "type": "string" } } },
      "Message": { "type": "object", "properties": { "id": { "type": "string" }, "message_id": { "type": "string" }, "to": { "type": "string" }, "subject": { "type": "string" }, "status": { "type": "string", "enum": ["queued", "sending", "sent", "delivered", "deferred", "bounced", "failed", "expired", "cancelled", "complained"] }, "priority": { "type": "string" }, "smtp_code": { "type": "string" }, "smtp_response": { "type": "string" }, "bounce_side": { "type": "string" }, "bounce_reason": { "type": "string" }, "bounce_label": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object" }, "sent_at": { "type": "string" }, "opened_at": { "type": "string" }, "clicked_at": { "type": "string" }, "expires_at": { "type": "string" }, "created_at": { "type": "string" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/MessageEvent" } } } },
      "Template": { "type": "object", "properties": { "key": { "type": "string", "example": "order-created" }, "name": { "type": "string" }, "active_version": { "type": "integer" }, "subject": { "type": "string" }, "html": { "type": "string" }, "text": { "type": "string" }, "versions": { "type": "array", "items": { "type": "object", "properties": { "version": { "type": "integer" }, "created_at": { "type": "string" } } } } } },
      "Contact": { "type": "object", "properties": { "email": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "phone": { "type": "string" }, "city": { "type": "string" }, "custom_fields": { "type": "object" }, "list_ids": { "type": "array", "items": { "type": "integer" } }, "consent_status": { "type": "string", "enum": ["onay", "ret", "bilinmiyor"] }, "consent_source": { "type": "string" }, "consent_at": { "type": "string" }, "consent_ref": { "type": "string" } } },
      "Paginated": { "type": "object", "properties": { "data": { "type": "array", "items": {} }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "last_page": { "type": "integer" } } } } }
    },
    "responses": {
      "Err": { "description": "Hata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
    }
  },
  "paths": {
    "/send": { "post": { "summary": "İşlemsel e-posta gönder", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendRequest" } } } }, "responses": { "202": { "description": "Kuyruğa alındı", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendResponse" } } } }, "402": { "$ref": "#/components/responses/Err" }, "403": { "$ref": "#/components/responses/Err" }, "409": { "$ref": "#/components/responses/Err" }, "422": { "$ref": "#/components/responses/Err" }, "429": { "$ref": "#/components/responses/Err" } } } },
    "/send/batch": { "post": { "summary": "Toplu işlemsel gönderim (500)", "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "defaults": { "$ref": "#/components/schemas/SendRequest" }, "messages": { "type": "array", "maxItems": 500, "items": { "$ref": "#/components/schemas/SendRequest" } } } } } } }, "responses": { "200": { "description": "accepted / rejected / results[]" } } } },
    "/messages": { "get": { "summary": "İleti listesi", "parameters": [{ "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "to_date", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "maximum": 100 } }], "responses": { "200": { "description": "Sayfalı", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Paginated" } } } } } } },
    "/messages/{id}": {
      "get": { "summary": "İleti durumu ve olay zaman çizelgesi", "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "msg_… kimliği ya da Message-ID" }], "responses": { "200": { "description": "İleti", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } }, "404": { "$ref": "#/components/responses/Err" } } },
      "delete": { "summary": "Kuyruktaki iletiyi iptal et", "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "cancelled" }, "409": { "$ref": "#/components/responses/Err" } } }
    },
    "/templates": { "get": { "summary": "İşlemsel şablonlar", "responses": { "200": { "description": "Liste" } } }, "post": { "summary": "Şablon oluştur (sürüm 1)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Template" } } } }, "responses": { "201": { "description": "Oluşturuldu" } } } },
    "/templates/{key}": { "get": { "summary": "Şablon ve sürümleri", "parameters": [{ "name": "key", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "Şablon" } } }, "put": { "summary": "Yeni sürüm oluştur ve etkinleştir", "parameters": [{ "name": "key", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "Güncellendi" } } }, "delete": { "summary": "Şablonu sil", "parameters": [{ "name": "key", "in": "path", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "Silindi" } } } },
    "/templates/{key}/activate/{version}": { "post": { "summary": "Eski sürümü etkinleştir", "parameters": [{ "name": "key", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "version", "in": "path", "required": true, "schema": { "type": "integer" } }], "responses": { "200": { "description": "Etkin sürüm değişti" } } } },
    "/verify": { "post": { "summary": "E-posta doğrulama (1 kredi)", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" } } } } } }, "responses": { "200": { "description": "Sonuç" } } } },
    "/check/content": { "post": { "summary": "İçerik ön kontrolü (spam skoru, denetim)", "responses": { "200": { "description": "Sonuç" } } } },
    "/me": { "get": { "summary": "Hesap bilgisi", "responses": { "200": { "description": "Hesap" } } } },
    "/webhooks": { "get": { "summary": "Webhook abonelikleri", "responses": { "200": { "description": "Liste" } } }, "post": { "summary": "Abonelik oluştur", "responses": { "201": { "description": "Oluşturuldu (secret bir kez döner)" } } } },
    "/contacts": { "get": { "summary": "Kişiler", "responses": { "200": { "description": "Sayfalı" } } }, "post": { "summary": "Kişi oluştur/güncelle", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" } } } }, "responses": { "200": { "description": "Kişi" } } } },
    "/contacts/{id}": { "put": { "summary": "Kişi güncelle", "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }], "responses": { "200": { "description": "Kişi" } } }, "delete": { "summary": "Kişi sil", "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }], "responses": { "200": { "description": "Silindi" } } } },
    "/lists": { "get": { "summary": "Listeler", "responses": { "200": { "description": "Sayfalı" } } }, "post": { "summary": "Liste oluştur", "responses": { "201": { "description": "Oluşturuldu" } } } },
    "/segments": { "get": { "summary": "Segmentler", "responses": { "200": { "description": "Sayfalı" } } } },
    "/campaigns": { "get": { "summary": "Kampanyalar", "responses": { "200": { "description": "Sayfalı" } } }, "post": { "summary": "Taslak kampanya oluştur", "responses": { "201": { "description": "Taslak" } } } }
  }
}