TR Dili değiştir
Bir gelen kutusu açın

API referansı

Üç uç nokta, girişte ve çıkışta JSON. Genel alan adlarında ne anahtar ne de hesap gerekir — bir isteği terminale yapıştırın, çalışsın.

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

https://grabmail.io/api/v1

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

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.

Sahip olduğunuz bir alan adında posta kutusu özeldir; bu yüzden istekler bir anahtar taşır — kutunun size ait olduğunu kanıtlayan da budur. Anahtar, alan adını doğrula yaptığınızda verilir, bir kez gösterilir ve burada yalnızca bir hash olarak saklanır: 

Authorization: Bearer <your key>

Özel bir alan adında yanlış veya eksik anahtar, unauthorized ile 401 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.

Uç Noktalar

GET /api/v1/mailbox

Bir adreste bekleyen her şey, en yeniden en eskiye. Test paketinizin yokladığı çağrı budur.

Parametreler

AdİçindeTürGerekliAçıklama
address query string evet Okunacak mailbox, örn. k7fq2m@grabmail.io.
limit query integer hayır Bu çağrıda kaç mesaj döndürüleceği, 1-200. Varsayılan 50, en yeniden eskiye. Mailbox'ı değil, tek yanıtı sınırlar — geçmişini okumak için before kullanın.
before query string hayır Halihazırda sahip olduğunuz en eski mesajın id'si; ondan sonraki sayfayı döndürür. Önceki yanıttaki next alanını geri gönderin. next null olduğunda her şeye sahipsiniz demektir.

Örnek

Bir kutuyu listele 
$ 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"
    }
  ]
}

Durum kodları

200
Mailbox okundu. Boş bir mailbox count: 0 ile 200 döner, asla 404 değil. next sonraki sayfanın imlecini taşır, sonda ise null.
400
Adres hatalı biçimlendirilmiş ya da before bir mesaj id'si değil.
400
address eksik veya geçerli bir adres değil.
404
Bu alan adı burada barındırılmıyor — MX kaydını kontrol edin.
429
Hız sınırı aşıldı. Retry-After içindeki süre kadar bekleyip tekrar deneyin.
GET /api/v1/message/{id}

Başlıklar, düz metin kısmı, HTML kısmı ve varsa ekler.

Parametreler

AdİçindeTürGerekliAçıklama
id path string evet Liste çağrısının döndürdüğü mesaj id'si.
mailbox query string evet Mesajın teslim edildiği adres.

Örnek

Bir mesaj oku 
$ 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": []
}

Durum kodları

200
Mesaj. Gönderen yalnızca düz metin gönderdiyse html null olur.
400
mailbox eksik veya geçersiz.
404
Bu mailbox'ta böyle bir mesaj yok — ya da saklama süresini geçmiş.
429
Hız sınırı aşıldı.
DELETE /api/v1/message/{id}

Saklama süresinin dolmasını beklemek yerine, hemen kaldırır.

Parametreler

AdİçindeTürGerekliAçıklama
id path string evet Kaldırılacak mesaj.
mailbox query string evet Teslim edildiği adres.

Örnek

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

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

Durum kodları

200
Silindi. Çağrı idempotenttir: iki kez silmek yine 200 döndürür.
400
mailbox eksik veya geçersiz.
404
Bu mailbox'ta böyle bir mesaj yok.
429
Hız sınırı aşıldı.

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 ve alan adınızdaki tüm adresler aynı uç noktalar üzerinden yanıt versin — öğrenilecek ikinci bir API yoktur ve posta kutuları yalnızca anahtarınızla okunabilir.

Alan adı bağla →