Twilio SendGrid (E-posta) Entegrasyonu

Twilio SendGrid, HTTP API üzerinden milyonlarca mail gönderebilen bulut e-posta servisidir. Panel, kendi App\Mail\Transport\SendGridApiTransport sınıfı ile harici Composer paketi gerektirmeden SendGrid'in v3 Mail Send API'sini kullanır. Tüm anahtarlar ve gönderici bilgileri admin panel üzerinden DB'ye kaydedilir; .env değiştirmeniz gerekmez.

1) SendGrid hesabı ve API Key

1. signup.sendgrid.com üzerinden ücretsiz hesap oluşturun (Free plan: aylık 100 mail/gün).
2. Sol menüden Settings → API Keys → Create API Key.
3. Restricted Access seçin ve şu izinleri verin:
   • Mail Send → Full Access
   • Mail Settings → Read Access
   • User Account → Read (test bağlantısı için)
   • Suppressions → Read (opsiyonel, raporlama için)
4. Üretilen SG.xxxxxxxxxx ile başlayan anahtarı tek seferlik kopyalayın; ileride bir daha gösterilmez.

2) Sender Authentication (Domain doğrulama)

Spam'e düşmemek için Domain Authentication şarttır.

1. SendGrid → Settings → Sender Authentication → Authenticate Your Domain.
2. Gönderici domain'inizi girin (ör. panel.example.com) ve sihirbazı tamamlayın.
3. SendGrid 3 adet CNAME kaydı verir:
   • emXXXX.example.com → SendGrid hostname
   • s1._domainkey.example.com → DKIM 1
   • s2._domainkey.example.com → DKIM 2
   Bu kayıtları DNS'e ekleyin, ~1 saat sonra "Verify" butonuna basın.
4. Mevcut Zimbra/cPanel/Plesk mail sunucularınız etkilenmez; SendGrid sadece kendine özgü subdomain ve DKIM selektörlerini kullanır. SPF kaydınızda mevcut include'ları silmeyin, gerekirse SendGrid include'unu ekleyin (v=spf1 include:_spf.google.com include:sendgrid.net ~all gibi).
5. DMARC: yeni başlıyorsanız mutlaka p=none ile başlayın, raporları izleyin, sonra p=quarantine ve nihayet p=reject'e geçin.

3) Panelde entegrasyonu açmak

1. Yönetici paneli → Entegrasyonlar sayfasını açın.
2. Twilio SendGrid (E-posta) kartını genişletin.
3. "Entegrasyonu etkinleştir" kutucuğunu işaretleyin.
4. Alanları doldurun:
   • API Key — SG. ile başlayan tam anahtar
   • Gönderici e-posta — Sender Authentication ile doğrulanmış adres (ör. [email protected])
   • Gönderici adı — alıcının görüceği isim (ör. firma adınız)
   • Reply-to — opsiyonel; cevapların geleceği adres
   • Pazarlama mailleri SendGrid ile — kampanyalar için (önerilen)
   • Transactional mailler SendGrid ile — sipariş/fatura/OTP mailleri de SendGrid'den çıkar (yüksek hacimde önerilir)
   • Sandbox modu — test için açın; gerçek mail gönderilmez ama API yanıtı 202 döner
5. Kaydet ve sonrasında "Bağlantıyı test et". Başarılı yanıt: SENDGRID: Baglanti basarili. Hesap: ...

4) Event Webhook (bounce / spam / unsubscribe otomatik işleme)

SendGrid, gönderdiğiniz her mailin teslim, açılma, tıklama, bounce, spam şikayeti ve listeden çıkma olaylarını POST request ile size geri bildirir. Panel bu istekleri otomatik işler ve KVKK kayıtlarına işler.

1. SendGrid → Settings → Mail Settings → Event Webhook → Edit.
2. HTTP Post URL alanına: https://<panel-adresiniz>/webhooks/sendgrid
3. İşaretleyin: delivered, bounce, dropped, spam_report, unsubscribe, group_unsubscribe. (Open/click opsiyonel.)
4. Signed Event Webhook (önerilen): Enable edin, çıkan Verification Key (Public) değerini kopyalayıp panel SendGrid kartındaki "Webhook Public Key" alanına yapıştırın → Kaydet.
5. Webhook Status bölümünden Test Your Integration butonuna basın; panel logunda 200 OK yanıtı görmelisiniz.

Webhook'un yaptığı işlem

• bounce / dropped → Müşterinin consent_marketing_email kapatılır, consent_log tablosuna sebep ile birlikte yazılır. Bir sonraki kampanya bu kişiye gönderilmez.
• spam_report → İYS / KVKK açısından kritik. consent kapatılır, log'a kaydedilir.
• unsubscribe / group_unsubscribe → consent kapatılır.
• delivered / open / click → İstatistik amaçlı kayıt (DB'de saklanmaz, sadece SendGrid panelinden izlenir).

5) KVKK ve yurt dışı veri aktarımı

SendGrid Twilio'ya bağlı bir ABD merkezli servistir. Mail gönderirken alıcının e-posta adresi yurt dışına aktarılmış sayılır. Bu nedenle:

• Müşteri hesap oluştururken "Yurt dışına veri aktarımı (KVKK md. 9)" rızası mutlaka istenir.
• SendGrid pazarlama gönderimi için aktif olduğunda, kampanya segment sayıları otomatik olarak consent_overseas_transfer = true olan müşteriler üzerinden hesaplanır.
• Bu rızayı vermeyen müşterilere kampanya maili gönderilmez; isterseniz onlara yerel SMTP üzerinden manuel mail gönderebilirsiniz.

6) Sık karşılaşılan hatalar

• HTTP 401 — API Key geçersiz veya silindi. Yeni anahtar üretip panelden güncelleyin.
• HTTP 403 — API Key'de "Mail Send" izni yok. Restricted access ayarlarını kontrol edin.
• "Sender does not exist" — from_email Sender Authentication'da doğrulanmamış. Single Sender ya da Domain Authentication tamamlayın.
• "Test Your Integration" 401 dönüyor — Webhook public key yanlış kopyalanmış olabilir. PEM bloğunu (-----BEGIN PUBLIC KEY----- dahil veya hariç) olduğu gibi yapıştırın; sistem otomatik temizler.
• Mailler spam'e düşüyor — Domain Authentication, DMARC ve SPF/DKIM eksik veya hatalı. mail-tester.com üzerinden 8/10 üzerinde skor alana kadar düzeltin.

İlgili belgeler

• KVKK Aydınlatma Metni
• Açık Rıza Metni
• Bilgi bankası → Pazarlama kampanyası gönderme

7) Son güncellemeler (panel davranışı)

• Tek buton ile test mail: Entegrasyonlar sayfasındaki "SendGrid direkt API" ve "Sadece Laravel mailer" butonları kaldırıldı. Artık tek bir "Test maili gönder" butonu vardır. Sistem otomatik karar verir:
  • SendGrid kart aktif VE "Transactional mailleri SendGrid ile gönder" seçili ise → SendGrid HTTP API üzerinden gönderir.
  • Aksi halde → Laravel'in default mailer'ı (.env MAIL_*) ile gönderir.
• Entegrasyon sıralaması: Entegrasyonlar sayfasında aktif olan kartlar otomatik olarak üste taşınır (özet sayfasındaki gibi). Pasif olanlar altta gruplanır. Aynı sayfaya tekrar girdiğinizde aradığınız aktif servisi listenin başında bulursunuz.
• "Sunucu logları" butonu kaldırıldı: Artık entegrasyonlar sayfasında log butonu yoktur. Yerine Ayarlar → Log menüsü geldi. SendGrid hata mesajının detayını görmek için: Ayarlar → Log → Kaynak: E-posta (SendGrid / Mailer) → "Logları getir".

8) Recipient-side spam filtreleri (MagicSpam, SpamAssassin vb.)

SendGrid HTTP 202 yanıtı verdiği halde mail alıcının kutusuna düşmüyorsa, sorun çoğu zaman alıcının mail sunucusundaki spam filtresidir — SendGrid değil. Plesk sunucularda en yaygın senaryo:

• Plesk → Tools & Settings → MagicSpam kuyruğuna mail "SPAM[block_list (38)]" kodu ile düşer.
• Çözüm:
  1. MagicSpam → Whitelist bölümüne SendGrid gönderim alan adınızı (ör. panel.example.com) ve gönderici e-posta adresinizi ekleyin.
  2. Mevcut quarantine'deki test mailini "Whitelist Sender" ile beyaz listeye alın.
  3. SendGrid IP havuzundan çıkıyorsa 167.89.0.0/17 ve 168.245.0.0/17 bloklarını whitelist'e eklemek toplu çözümdür (kontrol için Plesk → MagicSpam log).
• Test ipucu: İlk olarak kendi domain'iniz dışında bir alıcı kullanın (Gmail, Yahoo, Outlook). Eğer Gmail'e ulaşıyorsa sorun kesinlikle alıcı tarafındaki spam filtresidir, kod ya da SendGrid değil.
• Sunucunuzda SpamAssassin çalışıyorsa /etc/mail/spamassassin/local.cf içine whitelist_from *@example.com satırı eklenebilir.

9) Tanı için Ayarlar → Log paneli

Test mail başarısız olursa veya teslim edilmezse:

1. Ayarlar → Log sayfasına girin.
2. Kaynak: E-posta (SendGrid / Mailer), Satır: 200.
3. Logları getir. Aşağıdakilerden biri görünür:
   • SendGrid HTTP 401 → API Key yanlış / silinmiş.
   • HTTP 403 — The from address does not match a verified Sender Identity → Sender Authentication eksik.
   • NullTransport döndü → SendGrid kart kayıtlı değil veya credentials decrypt edilemedi.
   • Hiçbir log yok → Mail Laravel mailer ile gitmiş, transport hatası yok; sorun büyük ihtimalle alıcı sunucudaki spam filtresinde.

10) DİKKAT: Gönderici Kimliği (Sender Identity) zorunlu

SendGrid Mart 2022'den itibaren tüm /v3/mail/send isteklerinde from adresinin hesapta önceden doğrulanmış olmasını zorunlu kılıyor. Bu kural panel ayarlarıyla değil, SendGrid'in kendi politikasıyla ilgilidir. Doğrulanmamış bir adresten gönderim denemesi HTTP 403 — The from address does not match a verified Sender Identity hatasıyla reddedilir ve mail asla alıcıya gitmez.

10.1) En sık yapılan hata: farklı domain'den gönderim

Panel bir domain'den (ör. panel.webgaraj.com) çalışırken SendGrid entegrasyon kartındaki from_email alanına başka bir markanın adresi (ör. [email protected]) yazılıyor. SendGrid hesabında yalnızca webgaraj.com tarafı doğrulanmış olduğu için gelisimbulutu.com adresli tüm gönderimler 403 ile reddedilir.

Kural: Entegrasyonlar → Twilio SendGrid kartındaki from_email adresi, SendGrid hesabınızda aşağıdaki iki yoldan en az biri ile doğrulanmış olmalıdır.

10.2) Yol A — Single Sender Verification (hızlı, tek adres)

1. SendGrid panel → Settings → Sender Authentication → Verify a Single Sender.
2. "Create New Sender" ile kullanmak istediğiniz adresi (ör. [email protected]) girin.
3. O adrese gelen onay mailindeki linke tıklayın. Durum "Verified" olur.
4. Panelde Entegrasyonlar → Twilio SendGrid kartındaki from_email alanını bu adresle aynı yapın ve kaydedin.

Avantajı: 1-2 dakika. Kısıtı: Sadece o tek adres gönderim yapabilir. Farklı bir adresten göndermek isteyince baştan doğrulama gerekir.

10.3) Yol B — Domain Authentication (önerilen, kalıcı)

1. SendGrid panel → Settings → Sender Authentication → Authenticate Your Domain.
2. Göndermek istediğiniz ana domain'i girin (ör. webgaraj.com). DNS provider'ınızın adı sorulursa seçin; sadece CNAME talimatlarını değiştirir.
3. SendGrid size 3 adet CNAME verir (DKIM için s1._domainkey, s2._domainkey ve return-path için emXXXX).
4. Bu 3 CNAME'i domain'inizin DNS'ine (Cloudflare, Plesk DNS vb.) ekleyin. Cloudflare kullanıyorsanız bu 3 kayıt için "Proxy" kapalı (DNS only, gri bulut) olmalıdır.
5. SendGrid'de "Verify" butonuna basın. Üç satır da ✔ olunca tamamdır.
6. Artık @webgaraj.com ile biten her adres gönderici olabilir (ör. info@, noreply@, destek@).

10.4) "Domain doğrulandı ama hala 403 alıyorum" durumu

SendGrid Domain Authentication satırında em1234.webgaraj.com gibi SendGrid tarafından türetilmiş bir subdomain görünmesi tek başına ana domain'in doğrulanmış olduğu anlamına gelmez. Sadece return-path ve DKIM imzası için kullanılır. DNS'te 3 CNAME'in üçünün de SendGrid panelinde Valid olması gerekir; biri eksikse ana domain doğrulanmamış sayılır.

Kontrol: SendGrid → Authenticate Your Domain → domain'e tıkla → DNS Records tablosunda üç satırın da "Valid" olduğunu gör. Olmayan satır için dig CNAME sX._domainkey.example.com +short ile DNS yayıldı mı doğrula (5-30 dk sürebilir).

10.5) Farklı markalar / çoklu domain senaryosu

Birden fazla domain'den (örn. webgaraj.com ve gelisimbulutu.com) gönderim yapmak isterseniz, SendGrid'de her bir domain için ayrı ayrı Domain Authentication veya Single Sender Verification yapmanız gerekir. Bir hesapta sınırsız sayıda doğrulanmış domain bulundurulabilir.

10.6) Dogrulama durumunu panelde hızlıca görmek

SendGrid hesabınızda hangi domain/adreslerin doğrulandığını görmek için SSH'tan şu komut kullanılabilir (API key mevcut):

APIKEY=$(php artisan tinker --execute='echo (\App\Services\Integrations\SendGridService::activeCredentials()["api_key"] ?? "");' 2>/dev/null)
# Dogrulanmis single senders:
curl -sS -H "Authorization: Bearer $APIKEY" https://api.sendgrid.com/v3/verified_senders | python3 -m json.tool
# Dogrulanmis (authenticated) domainler:
curl -sS -H "Authorization: Bearer $APIKEY" https://api.sendgrid.com/v3/whitelabel/domains | python3 -m json.tool

10.7) Kontrol listesi

• ✅ SendGrid panelinde from_email adresi ya Single Sender olarak doğrulanmış ya da adresinin domain'i Domain Authentication ile tam doğrulanmış.
• ✅ Panelde Entegrasyonlar → Twilio SendGrid kartındaki from_email tam olarak doğrulanmış adresle aynı (büyük-küçük harf, boşluk farkı bile olmamalı).
• ✅ Test mail gönderimi başarılı (Entegrasyonlar → Twilio SendGrid → "Test maili gönder").
• ✅ Kampanya sonrası Posta günlüğü → Kampanya → sent satırı meta'sında message_id dolu (SendGrid'in X-Message-Id değeri).
• ✅ SendGrid Activity Feed'de aynı alıcı için "Delivered" görünüyor.

10.8) Failed queue temizliği

Doğrulama ayarlarını düzelttikten sonra eski başarısız kampanya işlerini kuyruktan temizleyip tertemiz bir test yapmak için:

php artisan queue:flush

Sonra panelden yeni bir kampanya gönderin. Bu sefer Posta günlüğü → Kampanya sekmesindeki sent satırının meta'sında message_id dolu gelmelidir.