Toplu Gönderim

Toplu gönderim yalnızca Marketing akış kimlik bilgileri ile kullanılabilir. İşlemsel kimlik bilgileri 400 BATCH_NOT_ALLOWED_FOR_TRANSACTIONAL hatası döndürür. Bu, işlemsel akışların toplu e-posta için kötüye kullanılmasını önler.

Toplu Gönderim Yapma

POST https://api.mail.land/v1/transactional/send-batch

Toplu e-posta gönder

curl -X POST https://api.mail.land/v1/transactional/send-batch \
  -H "X-API-Key: ml_pem_Ab3Kx9mN2pQ7rT4wL8yD..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": {
      "email": "[email protected]",
      "name": "Your Company"
    },
    "recipients": [
      {
        "email": "[email protected]",
        "name": "Alice",
        "variables": { "firstName": "Alice", "plan": "Pro" }
      },
      {
        "email": "[email protected]",
        "name": "Bob",
        "variables": { "firstName": "Bob", "plan": "Starter" }
      }
    ],
    "subject": "Hi {{firstName}}, check out what'\''s new",
    "htmlContent": "<h1>Hey {{firstName}}!</h1><p>Your {{plan}} plan just got an upgrade.</p>",
    "variables": {
      "companyName": "Acme Inc",
      "year": "2026"
    },
    "tags": ["product-update", "february-2026"],
    "batchName": "February Product Update"
  }'

İstek Alanları

Alan	Tür	Zorunlu	Açıklama
`from`	object	Evet	Gönderici adresi (`email` ve isteğe bağlı `name`)
`recipients`	array	Evet	Alıcı listesi (not: `to` değil `recipients`)
`recipients[].email`	string	Evet	Alıcı e-posta adresi
`recipients[].name`	string	Hayır	Alıcı görünen adı
`recipients[].variables`	object	Hayır	Alıcıya özel şablon değişkenleri
`subject`	string	Koşullu	`templateId` kullanılmadığı sürece zorunludur
`templateId`	string	Hayır	Kayıtlı bir şablon kullanın
`htmlContent`	string	Koşullu	HTML gövdesi (`templateId` yoksa zorunludur)
`textContent`	string	Hayır	Düz metin alternatifi
`variables`	object	Hayır	Genel değişkenler. `templateId` ayarlansın ya da ayarlanmasın uygulanır; anahtar çakışmasında alıcının kendi `recipients[].variables` değeri kazanır
`replyTo`	string	Hayır	Yanıt adresi
`batchName`	string	Hayır	Bu toplu gönderim için okunabilir ad
`tags`	array	Hayır	Analitik ve webhook filtreleme için etiketler
`customHeaders`	object	Hayır	Özel e-posta başlıkları
`tracking`	object	Hayır	Açılma/tıklama izleme geçersiz kılmaları
`ipPoolId`	string	Hayır	Özel IP havuzları için ayrılmıştır. Henüz kullanılamıyor: göndermek `400 IP_POOL_NOT_FOUND` döndürür. Boş bırakın.
`scheduledAt`	datetime	Hayır	Gelecekte teslim için zamanlama, en fazla 7 gün öncesine kadar
`externalBatchId`	string	Hayır	Sisteminizin toplu gönderim tanımlayıcısı: gönderilirse, yanıtta aynen `batchId` olarak döndürülür
`priority`	enum	Hayır	`Low`, `Normal` (varsayılan), `High`, `Critical`
`idempotencyKey`	string	Hayır	Aynı anahtar için tekrarlanan gönderimleri önler. `X-Idempotency-Key` başlığı tercih edilir

Alan adı farkına dikkat edin: toplu gönderim recipients kullanırken tekli gönderim to kullanır.

Yanıt

Durum: 202 Accepted

Toplu gönderim yanıtı

{
  "success": true,
  "batchId": "batch_f47ac10b58cc43729876fedcba098765",
  "messageIds": ["m_a1b2c3...", "m_d4e5f6..."],
  "totalRecipients": 2,
  "acceptedCount": 2,
  "rejectedCount": 0,
  "rejectedRecipients": [],
  "queuedAt": "2026-02-17T10:30:00Z",
  "estimatedCompletion": "2026-02-17T10:35:00Z",
  "isSandboxed": false
}

Alan	Tür	Açıklama
`batchId`	string	Benzersiz toplu gönderim tanımlayıcısı
`messageIds`	array	Alıcıya özel mesaj kimlikleri (pazarlama için `m_` önekli)
`totalRecipients`	int	İstekteki toplam alıcı sayısı
`acceptedCount`	int	Teslim için kabul edilen alıcı sayısı
`rejectedCount`	int	Reddedilen alıcı sayısı
`rejectedRecipients`	array	Reddedilen alıcıların nedenleriyle birlikte detayları
`estimatedCompletion`	datetime	Toplu gönderim işleminin tahmini tamamlanma zamanı

Değişken Birleştirme

Anahtarlar çakıştığında alıcıya özel değişkenler genel değişkenleri geçersiz kılar:

Değişken önceliği

{
  "variables": {
    "companyName": "Acme Inc",
    "greeting": "Hello"
  },
  "recipients": [
    {
      "email": "[email protected]",
      "variables": { "greeting": "Dear valued customer" }
    },
    {
      "email": "[email protected]"
    }
  ]
}

[email protected] alır: greeting = "Dear valued customer", companyName = "Acme Inc"
[email protected] alır: greeting = "Hello", companyName = "Acme Inc"

Hata İşleme

Toplu gönderime özgü hatalar:

Durum	Kod	Açıklama
`400`	`BATCH_NOT_ALLOWED_FOR_TRANSACTIONAL`	İşlemsel kimlik bilgisi toplu gönderim yapamaz
`400`	`VALIDATION_FAILED`	Toplu gönderim başına maksimum alıcı sayısı (10.000) aşıldı
`400`	`INVALID_REQUEST`	`scheduledAt` 7 günden fazla ileride ("Cannot schedule email more than 7 days in advance")
`400`	`TEMPLATE_NOT_FOUND`	`templateId` bu hesabın hiçbir aktif şablonunu adlandırmıyor (silinmiş bir şablon için de döndürülür)
`400`	`IP_POOL_NOT_FOUND`	`ipPoolId` bu hesaba atanmış hiçbir havuzu adlandırmıyor
`422`	`TEMPLATE_VARIABLE_MISSING`	Her alıcı için bir `{{placeholder}}` değeri yok (yalnızca bazıları için yoksa onlar atlanır ve `template_variable_missing: name` nedeniyle `rejectedRecipients` içinde listelenir). Hiçbir şey kuyruğa alınmaz
`400`	`BATCH_SEND_FAILED`	Tüm alıcılar engellendi
`429`	`RATE_LIMIT_EXCEEDED`	Hız sınırı aşıldı (kimlik bilgisi başına değil, workspace/plan düzeyinde)
`429`	`QUOTA_EXCEEDED`	Aylık kota tükendi

POST /v1/transactional/send için belgelenen hesap doğrulama ve politika kodları (SENDING_BLOCKED, ACTION_REQUIRED, DAILY_LIMIT_EXCEEDED, MARKETING_PAUSED ve diğerleri) burada da geçerlidir.

Kısmi başarı mümkündür: bazı alıcılar kabul edilirken diğerleri reddedilebilir (örn. engelleme listesindeki adresler). Yanıttaki rejectedRecipients alanını kontrol edin.

Sonraki Adımlar

REST API: tekli e-posta gönderim referansı
Şablonlar: toplu e-postalar için şablon oluşturma
Zamanlanmış E-postalar: toplu gönderimleri zamanlama

Toplu Gönderim

Toplu Gönderim YapmaBölüm bağlantısını kopyala

İstek AlanlarıBölüm bağlantısını kopyala

YanıtBölüm bağlantısını kopyala

Değişken BirleştirmeBölüm bağlantısını kopyala

Hata İşlemeBölüm bağlantısını kopyala