REST API

POST /v1/transactional/send aracılığıyla işlemsel e-postalar gönderin. Bu, MailLand üzerinden e-posta göndermenin birincil yoludur.

Kimlik DoğrulamaBölüm bağlantısını kopyala

API anahtarınızı X-API-Key başlığına ekleyin:

X-API-Key: ml_pet_Ab3Kx9mN2pQ7rT4wL8yD...

Kimlik bilgisi Api kanalının etkin olmasını ve bir Sending ürün kimlik bilgisi olmasını gerektirir.

Tek E-posta GöndermeBölüm bağlantısını kopyala

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

curl -X POST https://api.mail.land/v1/transactional/send \
  -H "X-API-Key: ml_pet_Ab3Kx9mN2pQ7rT4wL8yD..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": {"email": "[email protected]"},
    "to": [{"email": "[email protected]"}],
    "subject": "Hello from MailLand",
    "htmlContent": "<p>Your email content here</p>"
  }'

İstek GövdesiBölüm bağlantısını kopyala

{
  "from": {
    "email": "[email protected]",
    "name": "Your App"
  },
  "to": [
    {
      "email": "[email protected]",
      "name": "Jane Doe",
      "variables": {
        "firstName": "Jane",
        "orderNumber": "ORD-12345"
      }
    }
  ],
  "subject": "Your order #{{orderNumber}} has shipped",
  "htmlContent": "<h1>Hi {{firstName}},</h1><p>Your order #{{orderNumber}} is on its way.</p>",
  "textContent": "Hi {{firstName}}, Your order #{{orderNumber}} is on its way.",
  "replyTo": "[email protected]",
  "tags": ["order-shipped", "transactional"],
  "customHeaders": {
    "X-Entity-Ref-ID": "order-12345"
  },
  "tracking": {
    "opens": true,
    "clicks": true
  },
  "priority": "High",
  "idempotencyKey": "order-12345-shipped-v1"
}

Alan ReferansıBölüm bağlantısını kopyala

EklerBölüm bağlantısını kopyala

Her ek üç alan gerektirir:

{
  "attachments": [
    {
      "fileName": "invoice.pdf",
      "contentType": "application/pdf",
      "content": "JVBERi0xLjQKJ...",
      "inline": false
    },
    {
      "fileName": "logo.png",
      "contentType": "image/png",
      "content": "iVBORw0KGgoAAAA...",
      "contentId": "company-logo",
      "inline": true
    }
  ]
}

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

Durum: 202 Accepted

{
  "success": true,
  "jobId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "messageIds": ["t_a1b2c3d4e5f6..."],
  "acceptedRecipients": ["[email protected]"],
  "rejectedRecipients": [],
  "queuedAt": "2026-02-17T10:30:00Z",
  "isSandboxed": false
}

Reddedilen AlıcılarBölüm bağlantısını kopyala

Alıcılar çeşitli nedenlerle reddedilebilir:

{
  "success": true,
  "jobId": "...",
  "acceptedRecipients": ["[email protected]"],
  "rejectedRecipients": [
    {
      "email": "[email protected]",
      "reason": "Suppressed"
    },
    {
      "email": "[email protected]",
      "reason": "domain_typo",
      "suggestion": "[email protected]"
    }
  ]
}

Yaygın red nedenleri:

• Suppressed: adres engelleme listesinde (önceki geri dönüşler/şikayetler)
• disposable_domain: tek kullanımlık e-posta sağlayıcısı tespit edildi
• domain_typo: alan adında muhtemel yazım hatası (suggestion alanını içerir)

Ön KontrolBölüm bağlantısını kopyala

Gerçek isteği yapmadan önce gönderme yeteneğinizi doğrulayın:

GET https://api.mail.land/v1/transactional/send/check?recipientCount=1

curl https://api.mail.land/v1/transactional/send/check?recipientCount=1 \
  -H "X-API-Key: ml_pet_Ab3Kx9mN2pQ7rT4wL8yD..."

{
  "canSend": true,
  "rateLimitStatus": {
    "currentSecond": 2,
    "limitPerSecond": 50,
    "currentHour": 450,
    "limitPerHour": 5000,
    "currentDay": 8200,
    "limitPerDay": 50000
  },
  "monthlyUsed": 125000,
  "monthlyLimit": 500000
}

canSend değeri false ise, reason alanı nedenini açıklar (hız sınırı, kota, hesap durumu vb.).

Eşgüçlülük (Idempotency)Bölüm bağlantısını kopyala

Ağ zaman aşımından sonra yapılan yeniden deneme e-postayı iki kez teslim etmemelidir. Bir eşgüçlülük anahtarı verirseniz, yeniden deneme tekrar göndermek yerine özgün yanıtı tekrarlar.

Anahtarı başlık olarak gönderin (önerilir):

X-Idempotency-Key: order-12345-shipped-v1

Veya gövdedeki idempotencyKey alanını kullanın. Her ikisi de kabul edilir; ikisini birlikte yalnızca değerler aynıysa gönderebilirsiniz.

KurallarBölüm bağlantısını kopyala

• Kapsam. X-Idempotency-Key yalnızca POST /v1/transactional/send ve POST /v1/transactional/send-batch uç noktalarında kabul edilir. Başka hiçbir uç nokta onu okumaz.
• Biçim. 1–255 karakter: harf, rakam, _ ve -. Anahtarlar birebir karşılaştırılır; boşluk kırpma veya büyük/küçük harf eşitleme yapılmaz.
• Pencere. Bir anahtar 24 saat boyunca tekrarlanabilir kalır. Sonrasında aynı anahtar yeni bir istek sayılır.
• Tekrar. Pencere içindeki yeniden deneme özgün yanıtı birebir döndürür (aynı kimlikler, aynı durum) ve hiçbir şey göndermez.
• Benzersizlik. Anahtarlar hesap başına benzersizdir. Bir anahtarı farklı bir uç nokta için yeniden kullanmak 409 ile reddedilir; her işlem için ayrı anahtar kullanın.

Korelasyon KimliğiBölüm bağlantısını kopyala

Bir korelasyon kimliği ekleyerek istekleri sistemler genelinde izleyin:

X-Correlation-ID: my-app-order-12345

veya

X-Request-ID: my-app-order-12345

Korelasyon kimliği günlüklerde ve etkinlik akışında görünür.

Hız Sınırı BaşlıklarıBölüm bağlantısını kopyala

Başarılı yanıtlar IP başına hız sınırı bilgisi içerir:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 295

Gönderim ilke motoru tarafından hız sınırlandığında (429), Retry-After başlığı beklenecek saniyeyi belirtir:

Retry-After: 30

İşlemsel bir istek en fazla 5 alıcı içerebilir ve her alıcı hız sınırlarınıza sayılır. Bu sayı saniye başına sınırınızı aşıyorsa (örneğin dakikada 60 olan bir planda saniyede 1), aynı saniyede başka bir istek kabul edilmemişse istek kabul edilir; aksi halde Retry-After: 1 ile 429 alır ve dakika başına sınırınız içinde bir sonraki saniyede yeniden denendiğinde başarılı olur. Bkz. Hız Sınırları.

IP düzeyinde bir 429 ayrıca ISO-8601 UTC zamanı olarak X-RateLimit-Reset içerir.

Hata YanıtlarıBölüm bağlantısını kopyala

Tüm hatalar bir JSON gövdesi döndürür:

{
  "code": "ERROR_CODE",
  "message": "Human-readable description",
  "timestamp": "2026-02-17T10:30:00Z",
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}

Hata KodlarıBölüm bağlantısını kopyala

İşlemsel Alıcı SınırıBölüm bağlantısını kopyala

İşlemsel kimlik bilgileri, gönderme isteği başına en fazla 5 alıcı zorlar. Bu, işlemsel akışların toplu gönderim için kötüye kullanılmasını önler. Daha fazla alıcıya ihtiyacınız varsa toplu gönderim ile Pazarlama kimlik bilgisi kullanın.

Şablon KullanımıBölüm bağlantısını kopyala

Satır içi HTML yerine kayıtlı bir şablona başvurun:

{
  "from": { "email": "[email protected]" },
  "to": [
    {
      "email": "[email protected]",
      "variables": {
        "firstName": "Jane",
        "resetLink": "https://app.example.com/reset?token=abc123"
      }
    }
  ],
  "templateId": "t8x2m4q9zk7wpr",
  "variables": {
    "companyName": "Acme Inc"
  }
}

subject şablondan gelir. Anahtar çakışmasında, alıcının kendi to[].variables değeri genel variables değerlerini geçersiz kılar, satır içi içerikle aynı kural. Şablon oluşturma ve yönetme için Şablonlar sayfasına bakın.

Sonraki AdımlarBölüm bağlantısını kopyala

• Toplu Gönderim: aynı anda birden fazla alıcıya gönderin
• SMTP Relay: REST yerine SMTP ile gönderin
• Şablonlar: yeniden kullanılabilir e-posta şablonları oluşturun
• Zamanlanmış E-postalar: gelecekteki teslimat için e-posta zamanlayın