Üç 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: 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.
Bu API'deki tek kimlik bilgisi, aşağıda açıklanan hesabınızın anahtarıdır — ücretsiz hesapta bir tane, ücretli planlarda daha fazla. Bir anahtarın kendine ait bir düzeyi yoktur: her çağrı, hesabının o anki planına göre değerlendirilir; bu yüzden aynı anahtar, abone olduğunuz anda ücretsiz sınırlardan kurtulur ve premium havuzu açar, plan sona erdiğinde de ücretsiz kotaya döner. Genel alan adları anahtar istemez; onlarla gönderildiğinde çağrılarınızı IP adresiniz yerine hesabınıza sayar. Gönderilen bir anahtar bilinmiyor veya iptal edilmişse, hangi alan adı olursa olsun her uç noktada 401 ile unauthorized döner — böylece bir yazım hatası, boş görünen bir posta kutusu yerine hemen ortaya çıkar.
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:
97 ö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, API anahtarlarınız içindeki bir anahtarla, Authorization: Bearer gm_live_… ile okunur. Ücretli bir plana ait bir anahtar olmadan aynı istek 404 döner — barındırmadığımız bir alan adı için verilen yanıtla kelimesi kelimesine aynı, bilerek: böylece havuz isim tahmin edilerek taranamaz. Asla bir posta kutusu değil.
Havuzun alan adları nerede
GET /api/v1/domains, anahtarınızla genel alan adlarını ve havuzun alan adı isimlerini döndürür. Aynı çağrı anahtarsız — ya da ücretsiz veya süresi dolmuş bir hesabın anahtarıyla — genel alan adlarını, havuzda kaç alan adı olduğunu ve maliyetini döndürür, ama asla bir isim vermez: planın satın aldığı şey, onları tek kullanımlık posta kara listelerinin dışında tutmaktır. Giriş yapmış bir abone, havuzu ana sayfadaki alan adı seçicisinde de görür.
GET /api/v1/me, bir anahtarı tek başına değerlendiren tek çağrıdır: 200 ile plan, geçerli dönem, kullanılan ve kalan kota, tutulan adresler ve hız sınırınız gelir — ya da anahtar bilinmiyorsa veya iptal edildiyse 401unauthorized. Havuzda bir şey 404 döndürdüğünde önce bunu çağırın: o yanıt bir anahtar sorununu bilerek gizler, bu ise onu gösterir.
Her durum ve bunun nedeni. İlk ikisi, nedeni okunana kadar şaşırtıcı görünen durumlardır.
404
unknown_domain — anahtar yok ya da ücretsiz veya süresi dolmuş bir hesabın anahtarı gönderilmiş. Barındırmadığımız bir alan adı için verilen yanıtla bilerek aynıdır: ikisini ayırt etmek, havuzun isim tahminiyle listelenmesine izin verirdi. Anahtarı /api/v1/me ile kontrol edin.
401
unauthorized — gönderilen anahtar bilinmiyor veya iptal edilmiş. Hangi alan adı olursa olsun her uç noktada döner: bu, anahtar hakkında bir şey söyler, asla bir alan adı hakkında değil.
402
quota_reached — bu dönemin kotası doldu ve kotanın ötesinde devam etme kapalı. overage_cap / overage_funds — kotanın ötesinde devam etme açık, ancak belirlediğiniz tavana ulaşıldı veya bakiye yetersiz. Zaten tutulan adresler üç durumda da çalışmaya devam eder.
403
address_taken — o adresi başka bir abone tutuyor. Başka bir ad seçin.
409
address_limit — adres sayısını sınırlayan bir plan için ayrılmıştır. Bugün böyle bir plan yok.
429
rate_limited — ücretsiz planda (anahtarsız ya da ücretsiz bir anahtarla): dakikada 60 istekten fazlası ya da tek bir adreste saniyede birden fazla okuma; ücretli bir anahtarla: tek bir adreste saniyede 2, 3 veya 5 okumadan fazlası. daily_limit_reached — günlük 1.000 ücretsiz istek hakkı doldu. Ücretli planlarda ne dakikalık ne de günlük sınır vardır. İkisi de Retry-After içerir.
Tutulan adresler ve kota
Premium bir adres, onu geçerli bir anahtarla okuyan ilk hesap tarafından tutulur — herhangi bir uç noktada veya MCP üzerinden yapılan herhangi bir okuma yeterlidir, önceden ayırmaya gerek yoktur. Tutulduğu sürece o adresi yalnızca o hesap okuyabilir; başka herkes 403 alır. Siz onu panelden bırakana ya da plan bitene kadar tutulmaya devam eder — bitiş tarihinde, ek süre olmadan.
Kota birim sayar: premium bir adrese gelen bir ileti veya açılan yeni bir premium adres, hangisi önce olursa — bu yüzden açıp hiç okumadığınız bir adres de yine bir birim tüketir. Zaten tutulan bir adresi tekrar okumak ücretsizdir. Hiçbir plan, bir hesabın tuttuğu adres sayısını sınırlamaz; onu sınırlayan kotadır ve ne kadar kaldığını /api/v1/me gösterir.
Takma ad, premium adreslerde de
Her posta kutusu listesi bir alias taşır: aynı kutuya teslimat yapan ve onun hakkında hiçbir şey açığa vurmayan ikinci bir adres. Takma adı bir forma verin, adresi yoklayın; yalnızca takma adı elinde bulunduran her zaman boş bir kutu görür. Belirli bir adres için sabittir, ücretsizdir ve premium adresler için de genel adresler için olduğu gibi döner. Alan adı bize aittir ve bilerek hiçbir yerde listelenmez.
Dört çağrıda her şey
KEY="gm_live_…" # API anahtarları sayfanızdan, ücretli bir planla
# 1. Anahtarı kontrol et: plan, kalan kota, hız sınırı. Anahtar hatalıysa 401.
curl -s https://grabmail.io/api/v1/me -H "Authorization: Bearer $KEY"
# 2. Havuzu listele. İsimler yalnızca ücretli bir anahtarla yanıtta yer alır.
curl -s https://grabmail.io/api/v1/domains -H "Authorization: Bearer $KEY"
# 3. Bunlardan birinde bir kutuyu oku. Bu ilk okuma adresi tutar ve bir birim sayılır.
curl -sG https://grabmail.io/api/v1/mailbox -H "Authorization: Bearer $KEY" \
--data-urlencode "address=a7f3k2@one-of-the-pool.com"
# 4. Bir mesajı oku, aynı başlıkla.
curl -sG https://grabmail.io/api/v1/message/MESSAGE_ID -H "Authorization: Bearer $KEY" \
--data-urlencode "mailbox=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. Kota yalnızca premium havuzu sayar, başka hiçbir şeyi saymaz. Planlar ve fiyatlar planlar sayfası sayfasındadır.
Uç Noktalar
GET/api/v1/mailbox
Bir adreste bekleyen her şey, en yeniden en eskiye. Test paketinizin yokladığı çağrı budur.
Parametreler
Ad
İçinde
Tür
Gerekli
Açı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. nextnull olduğunda her şeye sahipsiniz demektir.
Posta kutusu okundu. Boş bir posta kutusu count: 0 ile 200 döner, asla 404 değil. next sonraki sayfanın imlecini taşır, sonda ise null. alias, buraya teslimat yapan ve bu adres hakkında hiçbir şey açığa vurmayan ikinci bir adrestir — address yerine bunu bir forma verin; yalnızca onu elinde bulunduran her zaman boş bir posta kutusu görür. Sabittir, ücretsizdir ve premium adresler için de döner.
400
Adres hatalı biçimlendirilmiş ya da before bir mesaj id'si değil.
400
address eksik veya geçerli bir adres değil.
401
Bir API anahtarı gönderildi ve bu anahtar bilinmiyor veya iptal edilmiş. Hatalı bir anahtar her alan adında reddedilir; genel alan adları zaten anahtar istemez.
402
Yalnızca premium havuz: planın kotası doldu — quota_reached, ya da kotanın ötesinde devam etme açıksa overage_cap / overage_funds. Zaten tutulan adresler çalışmaya devam eder.
403
Yalnızca premium havuz: o adresi başka bir abone tutuyor (address_taken).
404
Bu alan adı burada barındırılmıyor — MX kaydını kontrol edin. Ücretli bir plana ait bir anahtar olmadan okunan bir premium havuz alan adı, bilerek tam olarak bunu yanıtlar.
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.
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"
}
Kodunuzu asla message alanına göre dallandırmayın. Kullanılan hata kodları şunlardır: invalid_address, bad_cursor, unknown_domain, not_found, rate_limited, daily_limit_reached, unauthorized ve yalnızca premium havuzda quota_reached, overage_cap, overage_funds, address_taken ve address_limit.
Bazı hatalar bu iki alandan fazlasını taşır: ne yapılacağını söyleyen bir hint, bir docs bağlantısı, 404 ve 429 yanıtlarında havuzun fiyatını ve nasıl açılacağını içeren bir premium_pool bloğu, ücretsiz sınırdan kaynaklanan 429 yanıtında ise ücretli bir planın neleri kaldırdığını anlatan bir upgrade bloğu. Bunlar, yanıt gövdesini birinin adına okuyan bir asistan için yazılmıştır: asistan pes etmek yerine bu seçeneği iletebilsin diye.
Hız sınırları
Ücretsiz, anahtarsız: IP adresi başına dakikada 60 ve günde 1.000 istek. Bir posta kutusuna yapılan her çağrı sayılır — listeleme, ileti okuma, HTML gövdesi, ek, silme — her MCP araç çağrısı da öyle. Gün 00:00 UTC'de sıfırlanır.
Ücretsiz bir API anahtarıyla aynı kota IP adresinizi değil hesabınızı izler — çağrılarınız bir CI çalıştırıcısı gibi değişen adreslerden geldiğinde kullanışlıdır. Ücretsiz bir hesabın bir anahtarı vardır ve okuduğu kutular gelen kutularınızda listelenir. Ücretsiz anahtar oluştur
Bu sınırın içinde adres başına saniyede bir okuma geçerlidir: bir posta kutusunu saniyede bir yoklamak amaçlanan ritimdir.
Ücretli planlarda dakikalık sınır da günlük sınır da yoktur. Ücretli bir planın anahtarını Authorization: Bearer olarak gönderin; geriye yalnızca planın adres başına hızı kalır: her alan adında saniyede 2, 3 veya 5 istek, hesap başına sayılır. Premium planın başlangıç fiyatı ayda $12,99. Planları gör
Bu sitedeki gelen kutusu ücretsiz API kotanızı tüketmez: açık bıraktığınız sayfa, ihtiyacınız olduğu sürece yeni postayı denetlemeye devam eder.
Bir sınırı aştığınızda, tam saniye cinsinden bir Retry-After başlığıyla birlikte 429 alırsınız: dakikalık sınır ya da adres sınırı için rate_limited, günlük sınır için ise UTC gece yarısına kalan süreyle birlikte daily_limit_reached. Her ücretsiz yanıt ne kadar hakkınız kaldığını söyler: dakika için X-RateLimit-Remaining, gün için X-RateLimit-Daily-Remaining.
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.
