Olaylar: Poll ve Webhook

Teslim yaşam döngüsü olayları iki kanaldan izlenir; iki kanal da aynı olay şeklini kullanır (tek parser yazarsınız).

Uçlar (8)

GET/eventsPoll
POST/webhooksOluştur (secret BİR KEZ döner)
GET/webhooksListe
GET/webhooks/{id}Tekil
PUT/webhooks/{id}url / eventTypes / status
DELETE/webhooks/{id}Sil
POST/webhooks/{id}/rotate-secretYeni secret (bir kez döner)
POST/webhooks/{id}/testÖrnek olay gönderir (senkron)

Olay şekli

type: delivered | bounced | complained | opened
customerRef yalnız gönderimde verildiyse ve korelasyon kurulduysa yazılır.
data sabit alanları: email (her zaman), providerMessageId?, campaignId? (kampanya olayında), publicMessageId? (işlemsel olayda) + tipe özel detaylar (bounceType, bounceSubType, timestamp, ipAddress, userAgent vb. — sağlayıcı payload'ından geldiği kadarıyla).
Olaylar 30 gün saklanır.

Olay (poll + webhook)

{
  "id": "evt_…",
  "type": "delivered",
  "occurredAt": "2026-09-15T09:31:02.0000000Z",
  "customerRef": "hastane-42",
  "data": {
    "email": "hasta@example.com",
    "providerMessageId": "…",
    "publicMessageId": "pmsg_…",
    "campaignId": "cmp_…",
    "bounceType": "Permanent"
  }
}

Poll

GET/public/v1/eventsscoperead

Sorgu parametreleri

Ad	Tip	Zorunlu	Açıklama
`after`	string	hayır	Cursor: bu olay id'sinden sonraki olaylar döner. İlk çağrıda boş bırakın.
`types`	string	hayır	Virgülle ayrık filtre (`delivered,bounced,complained,opened` alt kümesi). Bilinmeyen değer 422 `validation_error`.
`limit`	integer	hayır	1–500 (varsayılan 100).

nextAfter'ı bir sonraki isteğin after'ı yapın. Boş sayfada nextAfter istekteki after olarak aynen döner; değeri körlemesine taşıyabilirsiniz. Poll ucu webhook tanımından bağımsız her zaman çalışır.

Hatalar

GET/events

curl "https://api.mailmaks.com/mail/api/public/v1/events?after=evt_…&types=delivered,bounced&limit=100" \
  -H "Authorization: Bearer mm_live_..."

Yanıt200

{
  "items": [
    {
      "id": "evt_…",
      "type": "delivered",
      "occurredAt": "2026-09-15T09:31:02.0000000Z",
      "customerRef": "hastane-42",
      "data": {
        "email": "hasta@example.com",
        "providerMessageId": "…",
        "publicMessageId": "pmsg_…",
        "campaignId": "cmp_…",
        "bounceType": "Permanent"
      }
    }
  ],
  "nextAfter": "evt_…"
}

Webhook aboneliği yönetimi

url: https zorunlu; localhost/private/loopback adresler reddedilir (422 invalid_url).
eventTypes boşsa dört tipe birden abone olunur.
Hesap başına en çok 3 endpoint (webhook_limit_reached, 422).
Oluşturma yanıtı endpoint alanlarına ek secret içerir (whsec_ + 64 hex) — yalnız bu yanıtta görünür, kaydedin. Sonradan görülemez; rotate-secret yenisini üretir ve eski secret'la üretilen imzalar anında geçersiz olur.
Endpoint durumları: active | disabled | auto_disabled. PUT ile yalnız active/disabled seçilebilir; auto_disabled bir endpoint'i active'e çekmek başarısızlık sayacını sıfırlar.
test ucu persist edilmeyen örnek bir delivered olayını senkron POST'lar; yanıt { delivered, httpStatus?, error? } — sayaçlara dokunmaz (tanı ucu).

Oluştur (secret BİR KEZ döner)

POST/public/v1/webhooksscopesend

Gövde

Ad	Tip	Zorunlu	Açıklama
`url`	string	evet	https zorunlu; localhost/private/loopback reddedilir.
`eventTypes`	string[]	hayır	`delivered` \| `bounced` \| `complained` \| `opened` alt kümesi; boşsa dördü birden.

Hatalar

POST/webhooks

curl -X POST https://api.mailmaks.com/mail/api/public/v1/webhooks \
  -H "Authorization: Bearer mm_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://ornek.com/mailmaks/webhook",
    "eventTypes": [
      "delivered",
      "bounced"
    ]
  }'

Yanıt200

{
  "id": "wh_…",
  "url": "https://ornek.com/mailmaks/webhook",
  "eventTypes": [
    "delivered",
    "bounced"
  ],
  "status": "active",
  "createdAt": "…",
  "secret": "whsec_…64 hex…"
}

Liste

GET/public/v1/webhooksscoperead

Hatalar

GET/webhooks

curl https://api.mailmaks.com/mail/api/public/v1/webhooks \
  -H "Authorization: Bearer mm_live_..."

Yanıt200

{
  "items": [
    {
      "id": "wh_…",
      "url": "https://ornek.com/mailmaks/webhook",
      "eventTypes": [
        "delivered",
        "bounced"
      ],
      "status": "active",
      "createdAt": "…"
    }
  ]
}

Tekil

GET/public/v1/webhooks/{id}scoperead

Path parametreleri

Ad	Tip	Zorunlu	Açıklama
`id`	string	evet	Webhook endpoint id'si.

Hatalar

GET/webhooks/{id}

curl https://api.mailmaks.com/mail/api/public/v1/webhooks/wh_… \
  -H "Authorization: Bearer mm_live_..."

Yanıt200

{
  "id": "wh_…",
  "url": "https://ornek.com/mailmaks/webhook",
  "eventTypes": [
    "delivered",
    "bounced"
  ],
  "status": "active",
  "createdAt": "…"
}

url / eventTypes / status

PUT/public/v1/webhooks/{id}scopesend

Path parametreleri

Ad	Tip	Zorunlu	Açıklama
`id`	string	evet	Webhook endpoint id'si.

Gövde

Ad	Tip	Zorunlu	Açıklama
`url`	string	hayır	Yeni URL (https zorunlu).
`eventTypes`	string[]	hayır	Abone olunan olay tipleri.
`status`	string	hayır	Yalnız `active` \| `disabled` seçilebilir; `auto_disabled` endpoint'i `active`'e çekmek sayacı sıfırlar.

Hatalar

PUT/webhooks/{id}

curl -X PUT https://api.mailmaks.com/mail/api/public/v1/webhooks/wh_… \
  -H "Authorization: Bearer mm_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "eventTypes": [
      "delivered",
      "bounced",
      "complained"
    ],
    "status": "active"
  }'

Yanıt200

{
  "id": "wh_…",
  "url": "https://ornek.com/mailmaks/webhook",
  "eventTypes": [
    "delivered",
    "bounced",
    "complained"
  ],
  "status": "active",
  "createdAt": "…"
}

Sil

DELETE/public/v1/webhooks/{id}scopesend

Başarıda 204 (gövdesiz).

Path parametreleri

Ad	Tip	Zorunlu	Açıklama
`id`	string	evet	Webhook endpoint id'si.

Hatalar

Yeni secret (bir kez döner)

POST/public/v1/webhooks/{id}/rotate-secretscopesend

Yeni secret üretir; eski secret'la üretilen imzalar anında geçersiz olur. Secret yalnız bu yanıtta görünür.

Path parametreleri

Ad	Tip	Zorunlu	Açıklama
`id`	string	evet	Webhook endpoint id'si.

Hatalar

POST/webhooks/{id}/rotate-secret

curl -X POST https://api.mailmaks.com/mail/api/public/v1/webhooks/wh_…/rotate-secret \
  -H "Authorization: Bearer mm_live_..."

Yanıt200

{
  "id": "wh_…",
  "url": "https://ornek.com/mailmaks/webhook",
  "eventTypes": [
    "delivered",
    "bounced"
  ],
  "status": "active",
  "createdAt": "…",
  "secret": "whsec_…yeni 64 hex…"
}

Örnek olay gönderir (senkron)

POST/public/v1/webhooks/{id}/testscopesend

Persist edilmeyen örnek bir delivered olayını senkron POST'lar; sayaçlara dokunmaz (tanı ucu). httpStatus/error yalnız ilgili durumda yazılır.

Path parametreleri

Ad	Tip	Zorunlu	Açıklama
`id`	string	evet	Webhook endpoint id'si.

Hatalar

POST/webhooks/{id}/test

curl -X POST https://api.mailmaks.com/mail/api/public/v1/webhooks/wh_…/test \
  -H "Authorization: Bearer mm_live_..."

Başarılı teslim200

{
  "delivered": true,
  "httpStatus": 200
}

Başarısız teslim200

{
  "delivered": false,
  "httpStatus": 500,
  "error": "…"
}

Webhook teslimi ve imza doğrulama

Her olay endpoint'inize Content-Type: application/json gövdesiyle POST edilir; başlıklar X-MailMaks-Signature ve X-MailMaks-Event-Id'dir.

İmza sözleşmesi: v1 = HMAC-SHA256(secret, "{t}.{body}") hex (küçük harf); t unix saniyesi, body HTTP gövdesinin ham bayt dizisi.

Teslim garantileri

2xx dışındaki her yanıt (ve 10 sn zaman aşımı) başarısız denemedir. Yeniden deneme aralıkları: 1 dk → 5 dk → 30 dk → 2 sa → 12 sa (toplam 5 deneme); sonra olay o endpoint için kalıcı failed olur.
Endpoint ardışık 20 başarısızlıkta otomatik auto_disabled olur (her başarı sayacı sıfırlar). Kapalı kaldığı süredeki olaylar webhook'a geriye dönük gönderilmez — GET /events ile telafi edin (after cursor'ınız kaldığı yerden devam eder).
Aynı olay birden çok kez teslim edilebilir (retry) — id (X-MailMaks-Event-Id) ile idempotent işleyin.
Sıra garantisi verilmez; occurredAt'e göre değerlendirin.

Teslim başlıkları

X-MailMaks-Signature: t=1757924262,v1=5f4a…e2c9
X-MailMaks-Event-Id:  evt_…

Doğrulama (pseudo)

t, v1   = parse(header "X-MailMaks-Signature")     # "t=...,v1=..."
payload = t + "." + raw_request_body               # gövdeyi AYRIŞTIRMADAN, ham haliyle
expect  = hex(hmac_sha256(secret, payload))
if not constant_time_equals(expect, v1): reject 400
if abs(now - t) > 300: reject 400                  # replay penceresi (öneri: 5 dk)
respond 2xx                                        # işlemeyi kuyruğa atıp hemen 200 dönün

Doğrulama (PHP)

<?php
$secret  = getenv('MAILMAKS_WEBHOOK_SECRET');           // whsec_...
$body    = file_get_contents('php://input');            // HAM gövde — json_decode ETMEDEN
$header  = $_SERVER['HTTP_X_MAILMAKS_SIGNATURE'] ?? ''; // t=...,v1=...

$parts = [];
foreach (explode(',', $header) as $kv) {
    [$k, $v] = array_pad(explode('=', $kv, 2), 2, '');
    $parts[trim($k)] = trim($v);
}

$t  = $parts['t']  ?? '';
$v1 = $parts['v1'] ?? '';

$expected = hash_hmac('sha256', $t . '.' . $body, $secret);

if (!hash_equals($expected, $v1)) { http_response_code(400); exit('bad signature'); }
if (abs(time() - (int)$t) > 300)  { http_response_code(400); exit('stale timestamp'); }

$event = json_decode($body, true);
// $event['type'], $event['data']['email'], $event['id'] ...
// Olayı kuyruğa yazıp HEMEN 200 dönün — 10 sn içinde yanıt gelmezse deneme başarısız sayılır.
http_response_code(200);