MailMaks Public API v1

Tüm istek ve yanıtlar JSON'dur (istisna: POST /uploads multipart, CSV export). Alan adları camelCase, hata kodları snake_case, tarih/saatler ISO 8601 UTC'dir. Yalnız HTTPS. Toplam 43 uç.

Taban URL

Tüm public uçlar https://api.mailmaks.com/mail/api tabanının altındaki public/v1/ önekiyle çağrılır.

Deploy notu

Kesin public host yayına alınırken netleşecek — bkz. Yayın öncesi netleşecekler. /mail/api yol öneki servis route'larından gelir; LB'nin path'i sadeleştirip sadeleştirmeyeceği deployda netleşir.

Hızlı başlangıç

Dört adımda ilk maili gönderip durumunu izleyin.

Adım 1 — API anahtarı alın

API anahtarları MailMaks portalından (Ayarlar → API Anahtarları) oluşturulur. Anahtar mm_live_ önekiyle başlar ve yalnız oluşturma anında bir kez gösterilir — sunucuda yalnız SHA-256 hash'i saklanır, kaybedilen anahtar geri getirilemez (yenisi oluşturulur, eskisi iptal edilir).

Anahtar oluştururken kapsam (scope) seçilir: send (gönderim ve yazma işlemleri) ve read (sorgular). Varsayılan ikisi birden. İsteğe bağlı IP allowlist tanımlanabilir; doluysa anahtar yalnız o IP'lerden çalışır.

Adım 2 — Gönderen kimliğinizi doğrulayın (DNS)

Mail gönderebilmek için doğrulanmış bir gönderen kimliği (domain veya e-posta adresi) gerekir. Domain kimliği önerilir: doğrulanan domain altındaki herhangi bir adres from olarak kullanılabilir.

Dönen kayıtları DNS sağlayıcınıza girin, ardından durumu tazeleyin. status alanı verified olduğunda gönderim yapılabilir. Mevcut kimliklerinizi ve durumlarını GET /identities ile listeleyebilirsiniz.

Adım 3 — İlk maili gönderin

POST /messages ile tek zarf gönderin; variables alanı {{degisken}} yer tutucularını subject/html/text'e uygular. Başarılı yanıt HTTP 200'dür.

Adım 4 — Durumu sorgulayın

status alanı sent → delivered (veya bounced / complained) olarak evrilir. Durum değişikliklerini anlık almak için webhook tanımlayın veya GET /events ucunu poll edin.

Adım 2 — kimlik ekle ve DNS kayıtlarını çek

# Kimlik ekle
curl -X POST https://api.mailmaks.com/mail/api/public/v1/identities \
  -H "Authorization: Bearer mm_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "type": "domain", "value": "ornek.com" }'

# DNS kayıtlarını çek (DKIM CNAME'leri, MAIL FROM MX/SPF, DMARC)
curl https://api.mailmaks.com/mail/api/public/v1/identities/{id}/dns-records \
  -H "Authorization: Bearer mm_live_..."

# Kayıtları girdikten sonra durumu tazele
curl -X POST https://api.mailmaks.com/mail/api/public/v1/identities/{id}/verify \
  -H "Authorization: Bearer mm_live_..."

Adım 3 — ilk mail

curl -X POST https://api.mailmaks.com/mail/api/public/v1/messages \
  -H "Authorization: Bearer mm_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": "randevu@ornek.com",
    "to": ["hasta@example.com"],
    "subject": "Randevu Hatırlatması — {{tarih}}",
    "html": "<p>Sayın {{ad}}, randevunuz {{tarih}} günüdür.</p>",
    "variables": { "ad": "Ayşe Yılmaz", "tarih": "18 Eylül 2026" }
  }'

Başarılı yanıt (HTTP 200)

{
  "messageId": "0100019...-...",
  "accepted": [ { "email": "hasta@example.com", "messageId": "0100019...-..." } ],
  "rejected": [],
  "creditsCharged": 1
}

Adım 4 — durum

curl https://api.mailmaks.com/mail/api/public/v1/messages/{messageId} \
  -H "Authorization: Bearer mm_live_..."

Kimlik doğrulama

Anahtar taşıma

Her istekte anahtar iki yoldan biriyle taşınır: Authorization: Bearer mm_live_... (önerilen) veya X-Api-Key: mm_live_... (alternatif).

Anahtar biçimi: mm_live_ öneki + rastgele gövde (256-bit CSPRNG). Test anahtarı yoktur; tek (canlı) ortam vardır.

Doğrulama sırası ve hata biçimi

Filtre sırası: anahtar → IP allowlist → hesap durumu → scope → oran sınırı. Hata zarfı her uçta düz JSON'dur.

Durum	HTTP	Kod
Anahtar yok / biçimsiz / bilinmiyor / iptal edilmiş / IP allowlist dışı	401	`invalid_api_key` — hangi adımda düştüğü bilinçli olarak sızdırılmaz, hepsi tek biçim
Hesap askıda	403	`account_suspended` — anahtar geçerli, hesap askıda; anahtarınızı değiştirmeyin, destekle iletişime geçin
Anahtarın scope'u yetersiz	403	`insufficient_scope`
Oran sınırı aşıldı	429	`rate_limited` + gövdede `retryAfterSeconds` + `Retry-After` header'ı

Anahtar taşıma

Authorization: Bearer mm_live_...        (önerilen)
X-Api-Key: mm_live_...                   (alternatif)

Hata zarfı

{ "code": "invalid_api_key", "message": "Geçersiz veya eksik API anahtarı." }

Scope'lar

Scope	Kapsadığı uçlar
`send`	Tüm gönderim ve yazma/yan etkili uçlar: `POST /messages`, `POST /messages/test`, `POST /uploads`, kampanya oluşturma + yaşam döngüsü aksiyonları, şablon oluşturma/güncelleme/silme/send-test, bastırma ekleme/silme, kimlik ekleme/silme/verify, webhook oluşturma/güncelleme/silme/rotate/test
`read`	Tüm sorgular: mesaj/kampanya/rapor/geçmiş sorguları, şablon listesi/tekili/render-preview, `balance`, `credits/history`, `identities` listesi, `dns-records`, `suppressions` listesi, `reputation`, `events`, webhook listesi/tekili

Ayrı bir "admin" scope'u yoktur (v1 kataloğu: send, read). Salt-okur/salt-hesap uçlar HTTP fiili POST olsa bile read scope'una bağlıdır (örnek: render-preview — durum değiştirmez).

Oran sınırı

Anahtar başına dakikada 120 istek (sabit pencere). Hesabınıza özel daha yüksek bir kademe tanımlanmışsa o geçerlidir.

Ayrıca hesap bazında günlük gönderim tavanı olabilir (daily_cap, HTTP 429): pencere Türkiye günüdür, Retry-After TR gece yarısına kalan saniyeyi taşır.

customerRef etiketi

Hesabınız kendi müşterilerine hizmet veriyorsa (bayilik/toptan model), her gönderime opsiyonel customerRef etiketi ekleyin:

Biçim: max 64 karakter, yalnız [A-Za-z0-9_-]; ihlal 422 validation_error. Boş/verilmemiş geçerlidir.
Yazıldığı yerler: POST /messages, POST /campaigns, POST /suppressions (manuel bastırma kayıtlarına).
Geri okunduğu yerler: olaylarda (customerRef alanı — webhook + poll), bastırma kayıtlarında (GET /suppressions?customerRef=… filtresi).
Amaç ölçüm ve ayıklamadır (hangi son-müşteri ne gönderdi, kimin bounce'u): izolasyon veya faturalama sınırı değildir — bastırma listesi ve itibar hesap genelinde ortaktır.
Etiket ilk günden konmazsa geçmiş veri geri kırılamaz — entegrasyonun başında ekleyin.