Dokümantasyon

Önizleme: useulas API’si henüz genel kullanıma açık değil. Bu sayfa yayına alacağımız arayüzü anlatır; ayrıntılar değişebilir. Erişim için bekleme listesine katıl.

Hızlı başlangıç

Tek endpoint, tek anahtar. Alıcıyı, kanal sırasını ve içeriği gönder; kanal seçimi ve fallback sunucuda yapılır.

curl -X POST https://api.useulas.com/v1/send \
  -H "Authorization: Bearer $USEULAS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": { "phone": "+905321234567" },
    "channels": ["whatsapp", "sms"],
    "content": { "text": "Doğrulama kodunuz: 483920" }
  }'

WhatsApp 30 saniye içinde teslim edilmezse aynı mesaj SMS ile gönderilir. Başka kod yazmanız gerekmez.

Kimlik doğrulama

Her istekte API anahtarını Authorization başlığında gönder:

Authorization: Bearer <api_key>

Anahtarı yalnızca sunucu tarafında tut; tarayıcıya veya mobil uygulamaya gömme.

Mesaj gönderme

POST /v1/send — tüm kanallar için tek çağrı.

{
  "to": {
    "email": "[email protected]",
    "phone": "+905321234567"
  },
  "channels": ["whatsapp", "sms", "email"],
  "fallback_after": 30,
  "content": {
    "subject": "Doğrulama kodunuz",
    "text": "Kodunuz: 483920",
    "html": "<p>Kodunuz: <b>483920</b></p>"
  },
  "idempotency_key": "otp-user-9931"
}

Alan	Açıklama
to	Alıcı. email ve/veya phone (E.164, ör. +905321234567).
channels	Kanal sırası: whatsapp, sms, email. Dizi hem kanal seçimini hem fallback sırasını belirler; tek eleman verilirse fallback yapılmaz. "auto" verilirse sıra alıcının geçmiş teslimat kayıtlarına göre belirlenir.
fallback_after	Saniye. Bir kanal bu süre içinde delivered dönmezse sıradaki kanala geçilir. OTP için 30, hatırlatma için 600 gibi.
content	Kanal bağımsız içerik. SMS text, e-posta subject + html, WhatsApp onaylı şablon + değişkenler kullanır. Kanala özel içerik için content.sms, content.email gibi alt anahtarlar.
idempotency_key	Aynı anahtarla gelen tekrar istekler yeni mesaj üretmez. Ağ hatasında güvenle tekrar deneyebilirsin.

Yanıt 202 Accepted ve bir message_id döner. Teslimat asenkrondur; sonuç webhook ile bildirilir.

HTTP/1.1 202 Accepted

{ "message_id": "<message_id>" }

Fallback nasıl çalışır

1. Mesaj channels dizisindeki ilk kanaldan gönderilir.
2. fallback_after süresi içinde teslimat onayı gelmezse ya da kanal hata dönerse sıradaki kanal denenir.
3. Fallback tetiklendikten sonra önceki kanaldan gelen geç teslimat onayı yeni gönderim başlatmaz; alıcı aynı mesajı iki kez almaz.
4. Tüm kanallar denenip ulaşılamazsa message.exhausted olayı gönderilir.

Bir numarada WhatsApp olup olmadığı önceden sorgulanamaz; bu yüzden fallback hata değil zaman aşımı üzerine kuruludur.

Webhook olayları

Olay modeli kanal bağımsızdır; her olay hangi kanaldan geldiğini channel alanında taşır. Her webhook imzalanır; imzayı doğrulamadan işlem yapma.

Olay	Ne zaman
message.queued	Kabul edildi, kuyrukta
message.sent	Sağlayıcı kabul etti
message.delivered	Alıcıya ulaştı
message.failed	Kanal başarısız, fallback tetiklendi
message.exhausted	Tüm kanallar denendi, ulaşılamadı
message.suppressed	Suppression listesi nedeniyle engellendi

SMTP ile e-posta

Hazır bir mail kütüphanen varsa standart SMTP ile de gönderebilirsin. Laravel’de tek konfigürasyon değişikliği yeterli:

MAIL_MAILER=smtp
MAIL_HOST=<panelde_gosterilir>
MAIL_PORT=<panelde_gosterilir>
MAIL_USERNAME=<smtp_kullanici>
MAIL_PASSWORD=<smtp_sifre>

SMTP yolunda yalnızca e-posta gönderilir; çok kanal ve fallback için API’yi kullan.

Gönderici alan adı

Paylaşımlı alt alan adı (varsayılan). Kaydolduğunda <hesabın>.useulas.com üzerinden göndermeye hazırsın. DNS’e dokunman gerekmez; SPF, DKIM ve return-path kayıtları bizim tarafımızda.

Kendi alan adın. email.alanadin.com gibi bir alt alan adından göndermek için panel sana eklemen gereken kayıtları tek ekranda listeler; “Doğrula” ile hepsini birlikte kontrol edersin.

Kayıt	Adet
SPF (TXT)	1
DKIM (TXT)	1
Return-path (CNAME)	1
DKIM (CNAME)	3

Bounce ve suppression

Her mesaj benzersiz bir return-path ile takip edilir. Kalıcı olarak geri dönen adresler hesabının suppression listesine otomatik eklenir; bu adreslere yapılan sonraki gönderimler message.suppressed olayıyla engellenir.