# E-posta teslim bildirimleri

> E-posta hizmetinizin teslim, açılma, geri dönme ve şikâyet olaylarını Sayproof'a iletmesi.

Kaynak: /tr/integrate/email-events/

E-posta hizmetiniz davetlerin alıcıya ulaşıp ulaşmadığını ve açılıp açılmadığını Sayproof'a bildirdiğinde:

- **İstatistikler › Davetler** sekmesindeki davet hunisi eksiksiz hesaplanır: gönderilen, ulaşan, açılan, adrese ulaşmayan ve yoruma dönüşen davetler.
- Kalıcı olarak geri dönen, şikâyet edilen ya da abonelikten çıkılan adresler otomatik olarak e-posta almak istemeyenler listesine eklenir ve bu adreslere yeniden davet gönderilmez.

Teslim bildirimi alınmazsa gönderim kayıtları "Gönderildi" durumunda kalır ve açılma oranı "bilinmiyor" olarak gösterilir; bu değer sıfır olarak sayılmaz.

## Bağlantının kurulması

1. **Entegrasyon** ekranının **E-posta teslim bildirimleri** sekmesindeki (yalnızca davetleri kendi sisteminiz gönderiyorsa görünür) **E-posta teslim bildirimleri** kartında **Bağla** düğmesine basın. **E-posta teslim bildirimi şifresi** yalnızca bir kez gösterilir.
2. Bağlandıktan sonra kartta kapalı duran **E-posta hizmetinize girilecek adresler** bölümünü açın; bölüm e-posta hizmetinize girilecek endpoint adreslerini listeler. Kullandığınız hizmetin webhook ayarına ilgili adresi girin.

| Hizmet | Kimlik doğrulama |
|---|---|
| Genel (şifreyle doğrulanan bildirim) | İstek, sipariş aktarımındaki imzalı gönderimle aynı üç header ile imzalanır |
| Amazon SES (SNS üzerinden), SendGrid, Postmark, Mailgun | Adres, markanıza özel bir erişim kodu içerir |

:::caution
Erişim kodu içeren adresleri bir şifre gibi saklayın ve paylaşmayın. Bir adresin başkalarının eline geçtiğinden şüpheleniyorsanız kartta **Bağlantıyı kes** ile bağlantıyı kesin ve yeniden kurun. Bu hizmetlerde kimlik, adresteki erişim koduyla doğrulanır.
:::

Kullandığınız hizmet, ilk olay ulaştığında kartta gösterilir.

Bağlantıyı kesmek için kartta **Bağlantıyı kes** düğmesine basın; onaydan sonra e-posta hizmetinizden gelen bildirimler alınmaz. Yeniden bağlamak için **Bağla** ile yeni bir şifre oluşturup e-posta hizmetinize girersiniz.

## Olaylar

| Olay | Etkisi |
|---|---|
| `delivered` | Gönderimin durumu "Ulaştı" olur |
| `deferred` | Gönderimin durumu "Gecikti, yeniden denenecek" olur |
| `opened` | "Açıldı" bilgisi kaydedilir; gönderim ulaşmış da sayılır |
| `bounced` | Gönderimin durumu "Adrese ulaşmadı" olur. Geri dönme kalıcıysa adres e-posta almak istemeyenler listesine eklenir |
| `complained` | Gönderimin durumu "Müşteri şikayet etti" olur ve adres listeye eklenir |
| `unsubscribed` | Adres listeye eklenir |

Durum yalnızca ileri doğru değişir: geç ulaşan bir `deferred` olayı "Ulaştı" durumunu geri almaz. Listeye adresin kendisi değil, yalnızca hash değeri yazılır. Hizmet bildirimleri (ret bildirimleri) bu listeden etkilenmez.

Listeye yalnızca Sayproof'un gönderdiği bir e-postayla eşleşen olay adres ekler; eşleşmeyen olay kaydedilir, `matched` sayısına girmez ve listeyi değiştirmez. Listeye eklenen adres e-postanın gönderildiği adrestir; olaydaki alıcı adresi farklıysa dikkate alınmaz.

## Genel biçim

Kendi e-posta sisteminiz ya da listede yer almayan bir hizmet için:

```http
POST https://api.sayproof.example/v1/mail-events/generic
Content-Type: application/json
X-Sayproof-Secret: SIFRE-KIMLIGI
X-Sayproof-Timestamp: 2026-09-28T10:00:00+03:00
X-Sayproof-Signature: …
```

```json
{
  "events": [
    {
      "type": "delivered",
      "reference": "GONDERIM-KIMLIGI",
      "message_id": "hizmetin-ileti-kimligi",
      "recipient": "ayse@ornek.com",
      "occurred_at": "2026-09-28T10:00:00+03:00",
      "permanent": false,
      "event_id": "evt-1",
      "detail": "hard_bounce"
    }
  ]
}
```

- Tek bir olay ya da en fazla 500 olaydan oluşan bir liste gönderilebilir; body en fazla 1 MB olabilir.
- `type` şu değerlerden biridir: `delivered`, `deferred`, `bounced`, `complained`, `opened`, `unsubscribed`. Diğer türler yanıttaki `ignored` sayısına eklenir ve işlenmez.
- `permanent: true` yalnızca `bounced` olayında dikkate alınır.
- `detail` kod olarak saklanır; içindeki e-posta adresleri saklanmadan önce `address` sözcüğüne çevrilir.
- Metin alanlarından birinde saklanamayan bir karakter (NUL `\u0000` ya da eşi olmayan vekil karakter) varsa istek `400 invalid / field_invalid` ile reddedilir.
- Daha önce işlenmiş bir `event_id` yeniden gönderilirse işlenmez ve `duplicates` sayısına eklenir.
- İmza kuralları [sipariş aktarımındakiyle](/tr/integrate/orders.md#imza) aynıdır. Şifre başına 5 dakikada 600 istek gönderilebilir.
- `X-Sayproof-Secret` header'ındaki kimlik, **Kanallar › Anahtarlar** sekmesinin **Gelişmiş: imzalı gönderim şifreleri** bölümündeki tabloda **E-posta teslim bildirimi şifresi** satırının **Şifre kimliği** sütunudur.

Yanıt: `{"accepted", "matched", "duplicates", "ignored", "opted_out"}`.

### Olayın e-postayla eşleştirilmesi

Sayproof bir olayın hangi e-postaya ait olduğunu önce `reference` alanından, bulamazsa hizmetin ileti kimliğinden (`message_id`) belirler.

- Sayproof'un gönderdiği her e-posta `X-Sayproof-Message` header'ını taşır. Bu değeri hizmetinizin olayında `reference` olarak geri gönderin. Hazır desteklenen hizmetlerde SendGrid için `custom_args.sayproof_message`, Postmark için `Metadata.sayproof_message`, Mailgun için `user-variables.sayproof_message` alanı okunur.
- [Davetleri kendi sisteminizden gönderiyorsanız](/tr/integrate/own-sending.md) Sayproof'tan gelen istekteki `event_id` değerini e-postaya `X-Sayproof-Message` header'ı olarak ekleyin; bu değer olayda `reference` olarak geri döner.