API referansı

Bütün istekler https://api.singlemail.singleton.com.tr adresine, Authorization: Bearer sm_… başlığıyla yapılır. Gövde ve yanıtlar JSON'dur.

E-posta gönderme

POST /emails

{
  "from": "Destek <destek@firma.com>",
  "to": ["ali@ornek.com"],
  "subject": "Talebiniz alındı",
  "html": "<p>…</p>",
  "tags": [{ "name": "type", "value": "ticket" }]
}

→ 200 { "id": "abe55c23-533d-41ad-8971-2dad84ad985b" }

Alan	Tür	Açıklama
`from`	string	Tek bir gönderen: "adres@domain" ya da "Ad <adres@domain>". Ad kısmında @ , ; : < > " olamaz; domain doğrulanmış olmalı.
`to`	string \| string[]	Alıcı(lar).
`subject`	string	Konu.
`html / text`	string	En az biri zorunlu.
`cc / bcc / reply_to`	string \| string[]	İsteğe bağlı.
`headers`	object	En fazla 20 özel başlık: List-Unsubscribe(-Post), In-Reply-To, References, X-*. From, Sender, Bcc gibi adres ve yönlendirme başlıkları reddedilir.
`tags`	{name, value}[]	Filtreleme ve webhook'larda geri dönen etiketler.
`attachments`	{filename, content \| path, content_type, content_id}[]	content base64 ya da path herkese açık bir URL (SingleMail indirir, en fazla 10 MB). content_id ile inline görsel.
`scheduled_at`	string	ISO tarih ya da "in 10 minutes".

E-postalar

Yöntem	Yol	Açıklama
POST	/emails	E-posta gönderir. Idempotency-Key başlığını destekler.
POST	/emails/batch	Tek istekte en fazla 100 e-posta gönderir.
GET	/emails	Gönderilen e-postaları listeler (?limit, ?after).
GET	/emails/:id	Tek bir e-postanın durumunu döner.
GET	/emails/:id/events	E-postanın olay geçmişi.
PATCH	/emails/:id	Zamanlanmış e-postanın tarihini değiştirir.
POST	/emails/:id/cancel	Zamanlanmış e-postayı iptal eder.

Domainler

Yöntem	Yol	Açıklama
POST	/domains	Domain ekler, DNS kayıtlarını döner.
GET	/domains	Domainleri listeler.
GET	/domains/:id	Domain ve DNS kayıtları.
PATCH	/domains/:id	Açılma/tıklama takibini açar veya kapatır.
POST	/domains/:id/verify	DNS kayıtlarını kontrol eder.
DELETE	/domains/:id	Domaini siler.

API anahtarları

Yöntem	Yol	Açıklama
POST	/api-keys	Anahtar oluşturur (full_access veya sending_access).
GET	/api-keys	Anahtarları listeler.
DELETE	/api-keys/:id	Anahtarı iptal eder.

Webhook'lar

Yöntem	Yol	Açıklama
POST	/webhooks	Webhook ekler, imza anahtarını (whsec_…) döner.
GET	/webhooks	Webhook'ları listeler.
GET	/webhooks/:id	Webhook ve imza anahtarı.
PATCH	/webhooks/:id	Adres, olaylar veya durumu günceller.
DELETE	/webhooks/:id	Webhook'u siler.

Engelli adresler

Yöntem	Yol	Açıklama
POST	/suppressions	Adresi engelli listesine ekler.
GET	/suppressions	Engelli adresleri listeler.
DELETE	/suppressions/:idOrEmail	Adresi listeden çıkarır.

Sayfalama

Liste uçları { object: "list", has_more, data } döner. ?limit= (en fazla 100) ve bir önceki sayfanın son kaydının ID'siyle ?after= kullanın.

Hatalar

Hatalı istekler şu gövdeyle döner: { statusCode, name, message }

Kod	name	Anlamı
401	`missing_api_key`	Authorization başlığı yok.
401	`restricted_api_key`	Sadece gönderim yetkili anahtarla yönetim ucu çağrıldı.
401	`restricted_api_key`	Sadece gönderim yetkili anahtarla e-posta okuma/iptal denendi.
403	`invalid_api_key`	Anahtar geçersiz.
429	`rate_limit_exceeded`	Bir IP'den 30 geçersiz anahtar denendi; 10 dakika bekleyin.
403	`project_suspended`	Proje ya da şirket yönetici tarafından askıya alındı.
403	`sending_paused`	Geri dönme ya da şikâyet oranı yükseldiği için gönderim duraklatıldı; yöneticiniz inceleyip devam ettirir.
403	`plan_limit_reached`	Planınızın domain ya da proje sınırı doldu.
403	`validation_error`	Domain kayıtlı veya doğrulanmış değil.
404	`not_found`	Kayıt bulunamadı.
409	`concurrent_idempotent_requests`	Aynı anahtarla ilk istek hâlâ işleniyor.
422	`validation_error`	Gövde hatalı; mesajda alan adı yazar.
422	`content_rejected`	İçerik spam gibi görünüyor; yanıttaki score ve reasons nedenini söyler.
422	`phishing_suspected`	Form, script, javascript: linki ya da IP adresine giden link var.
422	`attachment_rejected`	Çalıştırılabilir ya da makrolu dosya eki.
422	`recipient_rejected`	Tek kullanımlık, yazım hatalı ya da e-posta almayan alıcı domaini.
422	`blocklisted`	Platform kara listesindeki bir kelime ya da domain.
429	`rate_limit_exceeded`	Saniyelik istek sınırı aşıldı.
429	`monthly_quota_exceeded`	Planınızın aylık gönderim sınırı doldu; ayın 1'inde (UTC) sıfırlanır.
429	`warmup_limit_exceeded`	Yeni hesaplar ilk günlerde saatte sınırlı sayıda alıcıya gönderebilir.
429	`daily_quota_exceeded`	Planın ya da projenin günlük sınırı doldu; gece yarısı (UTC) sıfırlanır.

Koruma hataları

Spam ve kötüye kullanım koruması bir gönderimi reddettiğinde yanıtta hangi kontrolün devreye girdiği ve sebepleri de gelir. Engellenen gönderim saklanmaz ve kotanızdan düşmez. Toplu gönderimde bir e-posta reddedilirse hiçbiri gönderilmez; mesaj [3] gibi sırasıyla başlar.

422

{
  "statusCode": 422,
  "name": "content_rejected",
  "message": "Email content looks like spam (score 9.5): …",
  "check": "content",
  "score": 9.5,
  "reasons": [
    "Spam phrases: kazandiniz, hemen tikla (+3)",
    "Subject is in capital letters (+1.5)",
    "Uses a link shortener (+2)"
  ],
  "details": [
    { "code": "spam_phrases", "params": { "phrases": "kazandiniz, hemen tikla", "points": 3 } },
    { "code": "spam_subject_caps", "params": { "points": 1.5 } },
    { "code": "spam_shortener", "params": { "points": 2 } }
  ]
}

reasons İngilizce metindir ve değişebilir. Kendi arayüzünüzde sebebi göstermek ya da kodla karar vermek için aynı sırayla gelen details dizisindeki sabit code ve params alanlarını kullanın. Olası kodlar:

code	check	params	Örnek
`reputation_bounce_rate`	reputation	rate, limit	Son 24 saatte geri dönme oranı %7,4 (sınır %5,0)
`reputation_complaint_rate`	reputation	rate, limit	Son 24 saatte spam şikâyeti oranı %0,42 (sınır %0,30)
`reputation_paused`	reputation	—	İtibar koruması gönderimi duraklattı
`reputation_review_required`	reputation	—	Projeyi bir yöneticinin inceleyip devam ettirmesi gerekiyor
`warmup_limit`	warmup	hourly, days	Yeni hesaplar ilk 7 gün saatte en fazla 300 alıcıya gönderebilir
`recipient_disposable`	recipients	recipient, domain	Tek kullanımlık e-posta adresi: kisi@mailinator.com
`recipient_typo`	recipients	recipient, domain, suggestion	Yazım hatası olabilir: ahmet@gmial.com — gmail.com mu demek istediniz?
`recipient_reserved`	recipients	recipient, domain	Test için ayrılmış, e-posta alamayan domain: test@example.com
`recipient_no_mx`	recipients	recipient, domain	firma-yok.com.tr domaininin e-posta sunucusu yok: info@firma-yok.com.tr
`blocklist_keyword`	blocklist	keyword	Kara listedeki ifade: "deneme bonusu"
`blocklist_link_domain`	blocklist	domain	Kara listedeki domaine link: kumar-sitesi.example
`blocklist_recipient_domain`	blocklist	domain	Alıcı domaini kara listede: rakip.example
`blocklist_sender_domain`	blocklist	domain	Gönderen domaini kara listede: kumar-sitesi.example
`attachment_extension`	attachments	filename, ext	Çalıştırılabilir ek: fatura.pdf.exe
`attachment_content_type`	attachments	filename, contentType	Engellenen içerik türünde ek (application/x-msdownload): kurulum
`phishing_form`	phishing	—	HTML form içeriyor (e-posta bilgi toplamamalı)
`phishing_script`	phishing	—	Script, iframe ya da gömülü nesne içeriyor
`phishing_event_handler`	phishing	—	Satır içi JavaScript olayı içeriyor (onclick vb.)
`phishing_js_link`	phishing	—	javascript: ya da data: linki içeriyor
`phishing_userinfo`	phishing	host	Link gerçek hedefini kullanıcı@sunucu hilesiyle gizliyor: evil.example.net
`phishing_ip_link`	phishing	host	Doğrudan IP adresine link: 185.12.4.9
`spam_phrases`	content	phrases, points	Spam kalıpları: kazandiniz, hemen tikla (+3)
`spam_subject_caps`	content	points	Konu tamamen büyük harf (+1,5)
`spam_subject_exclamation`	content	points	Konuda çok fazla ünlem (+1)
`spam_money_symbols`	content	points	Para sembolleri ($$$) (+1)
`spam_shortener`	content	points	Link kısaltıcı kullanılmış (+2)
`spam_punycode`	content	points	Benzer görünümlü (punycode) domaine link (+1,5)
`spam_link_mismatch`	content	host, points	Link metni başka bir domain gösteriyor, hedefi farklı: secure-login.example.net (+3)
`spam_many_links`	content	points	Çok fazla link (+1)
`spam_lure`	content	points	Başka domaine giden hesap ya da ödeme tuzağı (+2,5)
`spam_image_only`	content	points	Metni olmayan, yalnızca görselden oluşan e-posta (+2)

Kendi linklerinizi tam adresle kullanmak, konuyu büyük harfle yazmamak ve link metninde başka bir domain göstermemek çoğu içerik reddini önler. Yanlış bir ret düşünüyorsanız SingleMail yöneticinizle görüşün; hesabınız için kontrolü ayarlayabilir.

ÖncekiWebhook'lar