API Anahtarları

API anahtarları (kimlik bilgileri) uygulamanızı MailLand API'si ile kimlik doğrular. Her anahtar ürün, mod, akış, kanal ile isteğe bağlı olarak etki alanı ve IP adresiyle kapsamlandırılır.

Panelde anahtarları kenar çubuğundaki Credentials (Global bölümü) altında oluşturup yönetin. Aynı işlemler aşağıda açıklanan /v1/credentials API'siyle de yapılabilir.

Bu sayfadaki Authorization: Bearer örnekleri, POST /v1/auth/login tarafından döndürülen JWT erişim belirtecini kullanır (bkz. Login). API anahtarları farklıdır: bunları X-API-Key başlığında gönderin, asla Bearer belirteci olarak değil.

Anahtar FormatıBölüm bağlantısını kopyala

Tüm MailLand API anahtarları şu formatı takip eder:

ml_{mode}{product}{stream?}_{random45chars}

• ml_: tüm anahtarlar için önek
• Mod: p (Production) veya s (Sandbox)
• Ürün: e (Sending), i (Inbound), v (Validation)
• Akış (yalnızca Sending): t (Transactional) veya m (Marketing)
• 45 rastgele karakter

Örnekler:

ml_pet_Ab3Kx9mN2pQ7rT4wL8yD...  → Production Sending Transactional
ml_sem_Xn7Kp2qR4tW9yB1cD6eF...  → Sandbox Sending Marketing
ml_pi_Mn5Jp8kL3rV6wA2xC4fG...   → Production Inbound
ml_pv_Qw9Er3tY6uI1oP5aS8dF...   → Production Validation

Kimlik Bilgisi ÖzellikleriBölüm bağlantısını kopyala

Bir kimlik bilgisi oluştururken aşağıdakileri yapılandırırsınız:

channels tek bir dizedir, asla dizi değildir. İki kanala izin vermek için "channels": "Api, Smtp" gönderin; ["Api", "Smtp"] 400 ile reddedilir.

Kimlik Bilgisi OluşturmaBölüm bağlantısını kopyala

curl -X POST https://api.mail.land/v1/credentials \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Transactional",
    "product": "Sending",
    "mode": "Production",
    "stream": "Transactional",
    "channels": "Api",
    "scope": "AllDomains",
    "rateLimitPerHour": 5000,
    "rateLimitPerDay": 50000
  }'

{
  "id": "n4k9pq2rt8mwxa",
  "name": "Production Transactional",
  "key": "ml_pet_Ab3Kx9mN2pQ7rT4wL8yD...",
  "keyPrefix": "ml_pet_Ab3Kx9mN",
  "product": "sending",
  "mode": "production",
  "stream": "transactional",
  "channels": "api",
  "scope": "allDomains",
  "sandboxBehavior": "logOnly",
  "rateLimitPerHour": 5000,
  "rateLimitPerDay": 50000,
  "isActive": true,
  "createdAt": "2026-02-17T10:00:00Z"
}

Kapsam: Etki Alanı KısıtlamalarıBölüm bağlantısını kopyala

Varsayılan olarak kimlik bilgileri, çalışma alanınızdaki herhangi bir doğrulanmış etki alanından gönderim yapabilir (AllDomains). Kimlik bilgilerini belirli etki alanlarıyla kısıtlamak için:

curl -X POST https://api.mail.land/v1/credentials \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Marketing - notifications.com only",
    "product": "Sending",
    "mode": "Production",
    "stream": "Marketing",
    "channels": "Api",
    "scope": "SelectedDomains",
    "domainIds": ["q7wm3nx9k2rtpz", "h5vy8jc2lspqwr"]
  }'

Etki alanı atamalarını oluşturma sonrasında da güncelleyebilirsiniz:

curl -X PUT https://api.mail.land/v1/credentials/n4k9pq2rt8mwxa/domains \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "domainIds": ["q7wm3nx9k2rtpz", "h5vy8jc2lspqwr"]
  }'

IP KısıtlamalarıBölüm bağlantısını kopyala

Kimlik bilgilerini belirli IP adresleri veya CIDR aralıklarıyla kısıtlayın:

curl -X PUT https://api.mail.land/v1/credentials/n4k9pq2rt8mwxa/allowed-ips \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "allowedIps": [
      { "ipAddress": "203.0.113.10", "description": "Production server" },
      { "ipAddress": "198.51.100.0/24", "description": "Office network" }
    ]
  }'

IP kısıtlamaları yapılandırıldığında, listelenmemiş IP'lerden gelen API istekleri 403 IP_NOT_ALLOWED döndürür.

Kanal YapılandırmasıBölüm bağlantısını kopyala

channels alanı kimlik bilgisinin nerede kimlik doğrulayabileceğini kontrol eder:

SMTP relay için kimlik bilgisi kullanmak üzere kanallar içinde Smtp değerinin bulunduğundan emin olun. SMTP üzerinden kimlik doğrularken herhangi bir kullanıcı adı ve API anahtarını parola olarak kullanın.

Anahtar DöndürmeBölüm bağlantısını kopyala

Bir yetkisiz kullanım süresiyle kesintisiz anahtar döndürme yapın:

curl -X POST https://api.mail.land/v1/credentials/n4k9pq2rt8mwxa/rotate \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "gracePeriodHours": 24
  }'

{
  "key": "ml_pet_Yn8Lq3rS5uW0zA4bC7dE...",
  "oldKeyExpiresAt": "2026-02-18T10:00:00Z"
}

Yetkisiz kullanım süresi boyunca (varsayılan 24 saat) hem eski hem de yeni anahtar geçerlidir. Yetkisiz kullanım süresinin ardından eski anahtar çalışmayı durdurur.

Sandbox ModuBölüm bağlantısını kopyala

“Sandbox” birbirinden ayrı iki şey anlamına gelir ve ikisi birleşir:

1. Sandbox kimlik bilgileri (mode: Sandbox). Geliştirme, CI/CD ve staging için. Bir gönderimin akıbeti kimlik bilgisinin sandboxBehavior değerine bağlıdır:

• LogOnly (varsayılan): istek doğrulanır ve 202 döner, ancak hiçbir şey teslim edilmez ve mesaj oluşturulmaz. Yanıtta isSandboxed: true, sandboxReason: "credential_sandbox_mode" ve boş messageIds bulunur.
• AllowListOnly: çalışma alanınızın sandbox izin listesine uyan alıcılara gerçekten teslim edilir; diğerleri rejectedRecipients içinde recipient_not_in_sandbox_allowlist nedeniyle döner. Hiçbir alıcıya izin yoksa yanıt yine 202 olur: acceptedRecipients: [] ve sandboxReason: "all_recipients_not_in_sandbox_allowlist".

SMTP üzerinden sandbox kimlik bilgisi asla teslim etmez: mesaj kabul edilip kaydedilir ancak sandboxBehavior ne olursa olsun gönderilmez.

2. Sandbox çalışma alanları. Yeni bir çalışma alanı Sandbox doğrulama düzeyinde başlar (bkz. Çalışma Alanları). Doğrulanana kadar Production kimlik bilgisiyle bile gönderim izin listesindeki alıcılarla sınırlıdır. Diğer her alıcı 429 SENDING_BLOCKED ile reddedilir (“Recipient '…' is not in sandbox allowlist. Add to allowlist or complete verification.”).

İzin listesini panelde Ayarlar → Sandbox Allow List altında yönetin. Bir kayıt bir adres ([email protected]) veya tüm alan adıdır (*@example.com). Aynı liste GET /v1/account/settings/sandbox-allowlist, POST /v1/account/settings/sandbox-allowlist, DELETE /v1/account/settings/sandbox-allowlist/{email} ile de kullanılabilir (panelin bearer belirteci; POST email ve isteğe bağlı description alır).

Kimlik Bilgilerini YönetmeBölüm bağlantısını kopyala

Kimlik bilgilerini listelemeBölüm bağlantısını kopyala

curl "https://api.mail.land/v1/credentials?limit=20" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Ürüne veya moda göre filtreleyin:

curl "https://api.mail.land/v1/credentials?product=Sending&mode=Production" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Kimlik bilgisi güncellemeBölüm bağlantısını kopyala

curl -X PATCH https://api.mail.land/v1/credentials/n4k9pq2rt8mwxa \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Name",
    "rateLimitPerHour": 10000,
    "isActive": false
  }'

Tüm alanlar isteğe bağlıdır: yalnızca değiştirmek istediklerinizi ekleyin.

Kimlik bilgisi silmeBölüm bağlantısını kopyala

curl -X DELETE https://api.mail.land/v1/credentials/n4k9pq2rt8mwxa \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Başarılı olduğunda 204 No Content döndürür. Silinen kimlik bilgileri hemen kimlik doğrulamayı durdutur. Silme anahtarı iptal eder: kimlik bilgisi GET /v1/credentials içinde isActive: false ile listelenmeye devam eder.

Hız SınırlarıBölüm bağlantısını kopyala

Her kimlik bilgisinin diğer kimlik bilgilerinden bağımsız kendi hız sınırları vardır:

Bir hız sınırı aşıldığında API X-RateLimit-* başlıklarıyla 429 döndürür:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1708171800
Retry-After: 45

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

• Hızlı Başlangıç: ilk e-postanızı gönderin
• REST API: tam gönderim API referansı
• SMTP Relay: API anahtarınızla SMTP üzerinden kimlik doğrulayın