API referansı

Genel Bakış

Bir posta kutusu hiçbir zaman oluşturulmaz — bir adrese mesaj ulaştığı anda var olur ve 5 gün sonra ortadan kalkar. Kaydedilecek hiçbir şey yoktur; bu yüzden genel alan adlarında API'nin kullanıcı, proje veya belirteç kavramı yoktur.

• Her yanıt, her hata dahil, JSON'dur.
• Tüm zamanlar RFC 3339 biçiminde UTC'dir — 2026-08-04T18:31:07Z.
• Mesaj kimlikleri opak dizelerdir. Ayrıştırmayın.
• Yalnızca alma. Tasarım gereği posta gönderen bir uç nokta yoktur.

Temel URL

Yalnızca HTTPS; düz HTTP yönlendirilir. Sürüm yol içinde yer alır ve v1 ayağınızın altında biçim değiştirmez — kırıcı bir değişiklik yeni bir numara alır.

Kimlik Doğrulama: Gerekmez

Genel alan adlarında hiçbiri yok. Bir adresi bilen herkes, tıpkı web sitesi üzerinden olduğu gibi API üzerinden de o kutunun postasını okuyabilir. Paylaşılan, geçici bir hizmetin anlaşması budur; bu yüzden önemsediğiniz hiçbir şeyi asla genel bir adrese yönlendirmeyin.

Buraya yönlendirdiğiniz bir alan adı da aynı uç noktalarda yanıt verir, yine anahtar olmadan. MX kaydını bize yönlendirin, ilk mesaj onu bağlar; bkz. bir alan adı bağlama. Üzerindeki posta kutuları, tıpkı genel alan adlarında olduğu gibi, adresi bilen herkes tarafından okunabilir.

Bir durumda hâlâ bir başlık kullanılır: istek üzerine kapattığımız bir alan adı Authorization: Bearer <key> ile okunur; yanlış veya eksik bir anahtar 401 ile unauthorized döner. Anahtarlar sabit sürede karşılaştırılır, bu yüzden yanlış bir anahtarı reddetmek, doğru bir anahtarı kabul etmek kadar sürer.

Premium alan adları

Yukarıdaki kuralın tek istisnası. Genel alan adları herkese açık tek kullanımlık posta engel listelerinde yer alır; bu yüzden bir kayıt formu bazen bu adreslerden birini reddeder. Ücretli bir plan şu havuzu açar: 92 özel .com alan adı, bu listelerin dışında tutulur.

API'de hiçbir şey değişmez. Aynı yollar, aynı parametreler, aynı yanıt biçimleri. Tek fark bir başlıktır: premium bir adres Authorization: Bearer gm_live_… ile, API anahtarlarınız içindeki bir anahtarla okunur. Geçerli anahtar olmadan aynı istek 402 veya 403 döner — asla bir posta kutusu değil.

# A public domain: no header at all.
curl -sG https://grabmail.io/api/v1/mailbox \
  --data-urlencode "address=a7f3k2@grabmail.io"

# A premium domain: the same call, plus a key.
curl -sG https://grabmail.io/api/v1/mailbox \
  -H "Authorization: Bearer gm_live_…" \
  --data-urlencode "address=a7f3k2@one-of-the-pool.com"

Genel alan adları ve kendi alan adlarınız, ücretsiz plan dahil tüm planlarda ücretsiz, anahtarsız ve sınırsız kalır. Kotalar yalnızca premium havuza gelen mesajları sayar. Planlar ve fiyatlar planlar sayfası sayfasındadır.

Uç Noktalar

$ curl -G https://grabmail.io/api/v1/mailbox \
  --data-urlencode "address=k7fq2m@grabmail.io"

{
  "address": "k7fq2m@grabmail.io",
  "count": 1,
  "next": null,
  "messages": [
    {
      "id": "01JR8W2K4Q",
      "from": "no-reply@example.com",
      "subject": "Your verification code",
      "date": "2026-08-04T18:31:07Z",
      "seen": false,
      "attachments": 0,
      "expires_at": "2026-08-09T18:31:07Z"
    }
  ]
}

$ curl -G https://grabmail.io/api/v1/message/01JR8W2K4Q \
  --data-urlencode "mailbox=k7fq2m@grabmail.io"

{
  "id": "01JR8W2K4Q",
  "from": "no-reply@example.com",
  "to": "k7fq2m@grabmail.io",
  "subject": "Your verification code",
  "date": "2026-08-04T18:31:07Z",
  "text": "Your code is 481920. It expires in 10 minutes.",
  "html": null,
  "attachments": []
}

$ curl -X DELETE -G https://grabmail.io/api/v1/message/01JR8W2K4Q \
  --data-urlencode "mailbox=k7fq2m@grabmail.io"

{
  "deleted": true,
  "id": "01JR8W2K4Q"
}

Ekler

Her mesaj, eklerini hazır bir URL ile listeler. Bunu, mesajın kendisiyle aynı yetkilendirmeyle getirin.

GET /api/v1/attachment/{id}?mailbox={address}

Gönderen ne etiketlemiş olursa olsun, her zaman Content-Disposition: attachment ile application/octet-stream döner. Bu bilinçli bir tercihtir: bir yabancının text/html'ini olduğu gibi yansıtmak, bir ekin bu kaynak üzerinde sayfa olarak çalışmasına izin verirdi. Gerçek tür, bir talimat değil veri olarak mesaj JSON'unda yer alır.

Hatalar

Her hata, aynı iki alana sahip JSON biçimindedir; böylece bir istemci bunları tek bir yerde işleyebilir. Durum kodu kategoriyi taşır, error sabit, makine tarafından okunabilir bir kısaltmadır ve message insanlar içindir ve her an yeniden ifade edilebilir.

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error":   "invalid_address",
  "message": "address must look like name@domain"
}

Asla message alanına göre dallanmayın. Kullanılan kısaltmalar invalid_address, unknown_domain, not_found ve rate_limited'dir.

Hız sınırları

Adres başına saniyede bir istek. Bir posta kutusunu saniyede bir yoklamak amaçlanan kullanım biçimidir ve asla kısıtlanmaz.

Sınırı aştığınızda saniye cinsinden Retry-After ile birlikte 429 alırsınız. Günlük bir kota veya yönetilmesi gereken bir patlama kredisi yoktur.

Saklama süresi

Bir mesaj, okunmuş olsun olmasın, ulaşmasından 5 gün sonra silinir. Her mesaj expires_at taşır, bu yüzden bu tarihi kendiniz hesaplamazsınız.

Bu bir ayar değil, kesin bir sınırdır — hiçbir parametre onu uzatmaz. Bir mesajın bu süreyi aşması gerekiyorsa, onu getirip kendi tarafınızda saklayın.

Kendi alan adınız

MX kaydınızı smtp.grabmail.io adresine yönlendirin, alan adınızdaki her adres aynı uç noktalardan yanıt versin — öğrenilecek ikinci bir API yok, kayıt yok, anahtar yok.

Alan adı bağla →