Mesajlar (işlemsel gönderim)

İşlemsel (transactional) gönderim yolu senkrondur: tek çağrı, tek SMTP zarfı, anında messageId. Zamanlanmış toplu gönderim için kampanya uçlarını kullanın.

Uçlar (5)

POST/messagesTekil/işlemsel gönderim
POST/uploadsEk yükleme
GET/messages/{id}Mesaj durumu
POST/messages/testTest gönderimi
GET/recipients/{email}/historyAdres bazlı geçmiş

Tekil/işlemsel gönderim

POST/public/v1/messagesscopesend

Header'lar

Ad	Tip	Zorunlu	Açıklama
`Idempotency-Key`	string	hayır	1–128 karakter, yalnız görünür ASCII. Bkz. Idempotency-Key.

Gövde

Ad	Tip	Zorunlu	Açıklama
`from`	string	hayır	Doğrulanmış kimlik adresi. Boşsa hesabın varsayılan kimliği kullanılır. Domain kimliğinde domain altındaki herhangi bir adres yazılabilir.
`to`	string[]	evet	En az 1, en çok 50 adres.
`cc`	string[]	hayır	CC alıcıları.
`bcc`	string[]	hayır	BCC alıcıları.
`subject`	string	evet	Konu. `{{degisken}}` desteklenir.
`html`	string	html veya text'ten biri	HTML gövde.
`text`	string	html veya text'ten biri	Düz metin gövde. Yalnız `html` verilirse `text` otomatik türetilir.
`variables`	object	hayır	`{{degisken}}` değerleri — subject/html/text'e uygulanır (HTML-encode'lu).
`attachments`	[{uploadId, fileName, size}]	hayır	Önceden POST /uploads ile yüklenmiş ek referansları. `fileName`/`size` bilgi amaçlıdır; sunucu yükleme kaydını esas alır.
`customerRef`	string	hayır	Ölçüm/ayıklama etiketi — bkz. customerRef. Max 64, `[A-Za-z0-9_-]`.
`scheduledAt`	string	—	Desteklenmez → 422 `scheduling_not_supported`. İşlemsel yol senkrondur; zamanlanmış toplu gönderim için kampanya ucunu kullanın.

Tek zarf semantiği (önemli)

Mesaj tek bir SMTP zarfıdır — to+cc+bcc aynı çağrıda, tek messageId ile gönderilir (CC'li mesajda alıcı başına ayrı kopya üretilmez). Kredi, to+cc+bcc geçerli alıcı toplamı kadar düşer. accepted satırlarının hepsinde aynı messageId görünür.

Alıcı işleme sırası: normalize + üç liste genelinde tekilleştirme (hem to hem cc'de geçen adres yalnız to'da kalır) → sentaks (invalid_syntax) → bastırma (suppressed) → MX ön doğrulaması (mx_fail) → kredi. Elenen her adres yanıtın rejected listesinde gerekçesiyle raporlanır.

Geçerli to alıcısı kalmazsa: 422 no_valid_recipients, kredi düşmez.
Kredi yetersizse: HTTP 200 döner, tüm geçerli alıcılar rejected'a reason: "quota" ile yazılır, kredi düşmez, messageId alanı yazılmaz.
Zarf gönderilemezse (sağlayıcı arızası): 502 send_failed, düşülen kredinin tamamı iade edilir.

Bastırma kapsamı: işlemsel yolda yalnız campaign_and_transactional kapsamlı bastırma kayıtları süzer. Pazarlama aboneliğinden çıkan (scope=campaign) bir adrese işlemsel mail (randevu, şifre sıfırlama…) gitmeye devam eder — tasarımın amacı budur.

Idempotency-Key

Idempotency-Key header'ı (1–128 karakter, yalnız görünür ASCII) yalnız POST /messages'ta desteklenir:

Aynı anahtar + aynı gövde 24 saat içinde tekrar gelirse saklanan yanıt aynen döner (ikinci gönderim yapılmaz, kredi tekrar düşmez). Tekrar yanıtında Idempotency-Replayed: true header'ı bulunur.
Aynı anahtar + farklı gövde → 409 idempotency_conflict.
Yalnız başarılı (200) yanıtlar saklanır: hata yanıtı (422/429/502…) saklanmaz — sorunu giderip aynı anahtarla güvenle yeniden deneyebilirsiniz.

rejected.reason değerleri: invalid_syntax | mx_fail | suppressed | quota.

Hatalar

POST/messages

curl -X POST https://api.mailmaks.com/mail/api/public/v1/messages \
  -H "Authorization: Bearer mm_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: randevu-2026-09-18-4471" \
  -d '{
    "from": "randevu@ornek.com",
    "to": [
      "hasta@example.com"
    ],
    "cc": [
      "sekreter@ornek.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"
    },
    "customerRef": "hastane-42"
  }'

Yanıt200

{
  "messageId": "…SES-MessageId…",
  "accepted": [
    {
      "email": "a@x.com",
      "messageId": "…aynı id…"
    }
  ],
  "rejected": [
    {
      "email": "bozuk@",
      "reason": "invalid_syntax"
    }
  ],
  "creditsCharged": 3
}

Ek yükleme

POST/public/v1/uploadsscopesend

multipart/form-data, dosya alan adı `file`. Tekil dosya sınırı 20 MB (aşımı 413 attachments_too_large).

Gövde

Ad	Tip	Zorunlu	Açıklama
`file`	file (multipart)	evet	Yüklenecek dosya. Tekil dosya ≤ 20 MB.

uploadId aynı hesabın POST /messages isteklerinde attachments alanında kullanılır; başka hesabın uploadId'si 404 not_found görünür.
Yükleme kaydının ömrü (TTL) 24 saattir; mesaj başarıyla gönderilince ek kaydı temizlenir, gönderilemeyen istekte TTL ile düşer (yeniden deneme hakkı).
Bir mesajın toplam ek boyutu 20 MB'ı aşamaz → 413 attachments_too_large.
Ekli mesaj Raw MIME olarak gönderilir; davranış (tek zarf, kredi, rejected) aynı kalır.

Hatalar

POST/uploads

curl -X POST https://api.mailmaks.com/mail/api/public/v1/uploads \
  -H "Authorization: Bearer mm_live_..." \
  -F "file=@sonuc.pdf"

Yanıt200

{
  "uploadId": "...",
  "fileName": "...",
  "size": 12345
}

Mesaj durumu

GET/public/v1/messages/{id}scoperead

Path parametreleri

Ad	Tip	Zorunlu	Açıklama
`id`	string	evet	Gönderim yanıtındaki `messageId` (iç kayıt id'si de kabul edilir).

status union'ı: sent | delivered | bounced | complained. Olay yoksa sent.
Çok alıcılı zarfta en kötü durum önceliği uygulanır: tek alıcının bounce'u mesajı bounced gösterir (öncelik: bounce > complaint > delivery).
cc/bcc boşsa alan hiç yazılmaz.

Hatalar

GET/messages/{id}

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

Yanıt200

{
  "messageId": "…",
  "status": "delivered",
  "from": "randevu@ornek.com",
  "subject": "…",
  "to": [
    "a@x.com"
  ],
  "cc": [
    "b@x.com"
  ],
  "rejected": [],
  "creditsCharged": 2,
  "createdAt": "2026-09-15T09:30:00.0000000Z"
}

Test gönderimi

POST/public/v1/messages/testscopesend

Panel "test maili" özelliğinin API karşılığı. Tek alıcı.

Gövde

Ad	Tip	Zorunlu	Açıklama
`from`	string	hayır	Çözümü `POST /messages` ile aynıdır (boşsa varsayılan kimlik).
`to`	string	evet	Tek alıcı adresi.
`subject`	string	evet	Konu.
`html`	string	evet	HTML gövde.

Kredi düşmez; bastırma ve MX ön doğrulaması uygulanmaz.
Ayrı bir oran sınırı yoktur (anahtar limiti 120/dk geçerlidir).

Hatalar

POST/messages/test

curl -X POST https://api.mailmaks.com/mail/api/public/v1/messages/test \
  -H "Authorization: Bearer mm_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": "randevu@ornek.com",
    "to": "test@ornek.com",
    "subject": "Test",
    "html": "<p>Merhaba</p>"
  }'

Yanıt200

{
  "messageId": "…"
}

Adres bazlı geçmiş

GET/public/v1/recipients/{email}/historyscoperead

Path parametreleri

Ad	Tip	Zorunlu	Açıklama
`email`	string	evet	Sorgulanan alıcı adresi.

Sorgu parametreleri

Ad	Tip	Zorunlu	Açıklama
`from`	string (ISO 8601)	hayır	Tarih aralığı başlangıcı.
`to`	string (ISO 8601)	hayır	Tarih aralığı bitişi.

kind: campaign | message. En yeni başta, en çok 500 satır.
status: kampanya satırında rapor union'ı (delivered/pending/bounced/complained/suppressed/failed), mesaj satırında mesaj union'ı (sent/delivered/bounced/complained).

Hatalar

GET/recipients/{email}/history

curl "https://api.mailmaks.com/mail/api/public/v1/recipients/hasta%40example.com/history?from=2026-09-01T00:00:00Z&to=2026-09-30T23:59:59Z" \
  -H "Authorization: Bearer mm_live_..."

Yanıt200

{
  "email": "hasta@example.com",
  "items": [
    {
      "kind": "message",
      "id": "…messageId…",
      "subject": "…",
      "status": "delivered",
      "date": "…"
    },
    {
      "kind": "campaign",
      "id": "cmp_…",
      "subject": "…",
      "status": "bounced",
      "date": "…"
    }
  ]
}