Drei Endpunkte, JSON rein und JSON raus. Kein Schlüssel und kein Konto bei öffentlichen
Domains — fügen Sie eine Anfrage in ein Terminal ein, und es funktioniert.
Übersicht
Ein Postfach wird nie angelegt — es entsteht in dem Moment, in dem eine Nachricht an einer
Adresse eintrifft, und ist 5 Tage später verschwunden. Es gibt
nichts zu registrieren, daher kennt die API bei öffentlichen Domains weder Benutzer,
Projekt noch Token.
Jede Antwort ist JSON, auch jeder Fehler.
Alle Zeiten sind UTC im RFC-3339-Format — 2026-08-04T18:31:07Z.
Nachrichten-IDs sind undurchsichtige Zeichenketten. Nicht parsen.
Nur Empfang. Es gibt bewusst keinen Endpunkt zum Versenden von E-Mails.
Basis-URL
https://grabmail.io/api/v1
Nur HTTPS; einfaches HTTP wird umgeleitet. Die Version steht im Pfad, und
v1 ändert die Form nicht unter Ihnen — eine Breaking Change bekommt
eine neue Nummer.
Authentifizierung: keine
Keine bei öffentlichen Domains. Wer eine Adresse kennt, kann
das zugehörige Postfach lesen — über die API genauso wie über die Website. Das ist
der Kompromiss eines geteilten Wegwerf-Dienstes: Nutzen Sie niemals eine öffentliche Adresse
für etwas, das Ihnen wichtig ist.
Eine Domain, die Sie hierher ausrichten, antwortet ebenfalls ohne Schlüssel über dieselben Endpunkte. Richten Sie den MX auf uns aus, und die erste Nachricht verbindet sie; siehe eine Domain verbinden. Postfächer darauf sind für jeden lesbar, der die Adresse kennt, genau wie bei den öffentlichen Domains.
Der einzige Zugangsschlüssel in dieser API ist der Schlüssel Ihres Kontos, unten beschrieben — einer mit einem kostenlosen Konto, mehr mit den bezahlten Tarifen. Ein Schlüssel hat keine eigene Stufe: Jeder Aufruf wird nach dem Tarif beurteilt, den sein Konto in diesem Moment hat. Derselbe Schlüssel verliert also die kostenlosen Grenzen und öffnet den Premium-Pool, sobald Sie abonnieren, und kehrt zum kostenlosen Kontingent zurück, wenn der Tarif endet. Die öffentlichen Domains brauchen keinen; dort mitgesendet, zählt er Ihre Aufrufe für Ihr Konto statt für Ihre IP-Adresse. Ein gesendeter Schlüssel, der unbekannt oder widerrufen ist, antwortet auf jedem Endpunkt 401 mit unauthorized, unabhängig von der Domain — ein Tippfehler zeigt sich so sofort, statt als Postfach, das leer aussieht.
Premium-Domains
Die einzige Ausnahme von der obigen Regel. Die öffentlichen Domains
stehen auf den öffentlichen Wegwerf-Mail-Sperrlisten, weshalb ein Anmeldeformular
eine Adresse darauf manchmal ablehnt. Ein kostenpflichtiger Tarif öffnet einen Pool von
97 private .com-Domains, von diesen Listen ferngehalten.
An der API ändert sich nichts. Gleiche Pfade, gleiche Parameter, gleiche Antwortformen. Der einzige Unterschied ist ein Header: eine Premium-Adresse wird mit Authorization: Bearer gm_live_… gelesen, mit einem Schlüssel aus Ihre API-Schlüssel. Ohne einen Schlüssel aus einem bezahlten Tarif antwortet dieselbe Anfrage 404 — Wort für Wort dieselbe Antwort wie bei einer Domain, die wir nicht hosten, absichtlich, damit der Pool nicht durch Erraten von Namen aufgelistet werden kann. Nie mit einem Postfach.
Wo die Domains des Pools sind
GET /api/v1/domains gibt mit Ihrem Schlüssel die öffentlichen Domains und die Domainnamen des Pools zurück. Derselbe Aufruf ohne Schlüssel — oder mit einem Schlüssel aus einem kostenlosen oder abgelaufenen Konto — liefert die öffentlichen Domains, wie viele Domains der Pool enthält und was er kostet, aber nie einen Namen: Sie von den Blocklisten für Wegwerf-Mail fernzuhalten ist das, wofür der Tarif bezahlt. Ein angemeldeter Abonnent sieht den Pool außerdem in der Domain-Auswahl auf der Startseite.
GET /api/v1/me ist der einzige Aufruf, der einen Schlüssel für sich allein beurteilt: 200 mit dem Tarif, der aktuellen Periode, dem verbrauchten und verbleibenden Kontingent, den gehaltenen Adressen und Ihrem Ratenlimit — oder 401unauthorized, wenn der Schlüssel unbekannt oder widerrufen ist. Rufen Sie ihn zuerst auf, wenn etwas im Pool mit 404 antwortet: Diese Antwort verbirgt ein Schlüsselproblem absichtlich, dieser Aufruf zeigt es.
Jeder Fall, mit dem Grund dafür. Die ersten beiden wirken überraschend, bis man den Grund liest.
404
unknown_domain — kein Schlüssel, oder ein Schlüssel aus einem kostenlosen oder abgelaufenen Konto. Absichtlich identisch mit der Antwort für eine Domain, die wir nicht hosten: Die beiden zu unterscheiden würde erlauben, den Pool durch Erraten von Namen aufzulisten. Prüfen Sie den Schlüssel mit /api/v1/me.
401
unauthorized — der gesendete Schlüssel ist unbekannt oder widerrufen. Die Antwort erfolgt auf jedem Endpunkt, unabhängig von der Domain: Sie sagt etwas über den Schlüssel aus, nie über eine Domain.
402
quota_reached — das Kontingent dieser Periode ist aufgebraucht, und der Mehrverbrauch ist ausgeschaltet. overage_cap / overage_funds — der Mehrverbrauch ist eingeschaltet, aber die von Ihnen gesetzte Obergrenze ist erreicht oder das Guthaben reicht nicht aus. Bereits gehaltene Adressen funktionieren in allen drei Fällen weiter.
403
address_taken — ein anderer Abonnent hält diese Adresse. Wählen Sie einen anderen Namen.
409
address_limit — reserviert für einen Tarif, der die Anzahl der Adressen begrenzt. Das tut heute kein Tarif.
429
rate_limited — im kostenlosen Tarif (ohne Schlüssel oder mit einem kostenlosen) mehr als 60 Anfragen pro Minute oder mehr als ein Lesevorgang pro Sekunde auf einer Adresse; mit einem Schlüssel aus einem bezahlten Tarif mehr als 2, 3 oder 5 Lesevorgänge pro Sekunde auf einer Adresse. daily_limit_reached — die 1.000 kostenlosen Anfragen des Tages sind aufgebraucht. Bezahlte Tarife haben weder das Minuten- noch das Tageslimit. Beide liefern Retry-After mit.
Gehaltene Adressen und das Kontingent
Eine Premium-Adresse wird von dem ersten Konto gehalten, das sie mit einem gültigen Schlüssel liest — jeder Lesevorgang, auf jedem Endpunkt oder über MCP, nichts, das man vorher reservieren müsste. Solange sie gehalten wird, kann nur dieses Konto sie lesen; jedes andere bekommt 403. Sie bleibt gehalten, bis Sie sie im Dashboard freigeben oder der Tarif endet — an seinem Enddatum, ohne Kulanzfrist.
Das Kontingent zählt Einheiten: eine auf einer Premium-Adresse empfangene Nachricht oder eine neu geöffnete Premium-Adresse, je nachdem, was zuerst eintritt — eine Adresse, die Sie öffnen und nie lesen, verbraucht also trotzdem eine Einheit. Eine bereits gehaltene Adresse erneut zu lesen ist kostenlos. Kein Tarif begrenzt, wie viele Adressen ein Konto hält; diese Grenze setzt allein das Kontingent, und /api/v1/me zeigt, was noch übrig ist.
Der Alias, auch bei Premium-Adressen
Jede Postfachauflistung trägt einen alias: eine zweite Adresse, die an dasselbe Postfach zustellt und nichts darüber verrät. Geben Sie den Alias an ein Formular weiter und fragen Sie die Adresse ab; wer den Alias hat, sieht immer ein leeres Postfach. Er ist für eine gegebene Adresse stabil, kostenlos, und wird für Premium-Adressen genauso zurückgegeben wie für öffentliche. Seine Domain ist eine der unseren und wird absichtlich nirgendwo aufgeführt.
Das Ganze in vier Aufrufen
KEY="gm_live_…" # von Ihrer API-Schlüssel-Seite, mit einem bezahlten Tarif
# 1. Schlüssel prüfen: Tarif, verbleibendes Kontingent, Ratenlimit. 401, wenn er ungültig ist.
curl -s https://grabmail.io/api/v1/me -H "Authorization: Bearer $KEY"
# 2. Pool auflisten. Die Namen stehen nur mit einem bezahlten Schlüssel in der Antwort.
curl -s https://grabmail.io/api/v1/domains -H "Authorization: Bearer $KEY"
# 3. Ein Postfach auf einer davon lesen. Dieser erste Lesevorgang hält die Adresse und zählt als eine Einheit.
curl -sG https://grabmail.io/api/v1/mailbox -H "Authorization: Bearer $KEY" \
--data-urlencode "address=a7f3k2@one-of-the-pool.com"
# 4. Eine Nachricht lesen, gleicher Header.
curl -sG https://grabmail.io/api/v1/message/MESSAGE_ID -H "Authorization: Bearer $KEY" \
--data-urlencode "mailbox=a7f3k2@one-of-the-pool.com"
Die öffentlichen Domains und Ihre eigenen bleiben in jedem Tarif kostenlos, schlüssellos und unbegrenzt — auch im kostenlosen. Das Kontingent zählt nur den Premium-Pool und sonst nichts. Tarife und Preise stehen auf die Tarifseite.
Endpunkte
GET/api/v1/mailbox
Alles, was an einer Adresse wartet, neueste zuerst. Diesen Aufruf pollt Ihre Testsuite.
Parameter
Name
Eingabe
Typ
Erforderlich
Beschreibung
address
query
string
ja
Das zu lesende Postfach, z. B. k7fq2m@grabmail.io.
limit
query
integer
nein
Wie viele Nachrichten dieser Aufruf liefert, 1–200. Standard 50, neueste zuerst. Begrenzt nur die Antwort, nicht das Postfach — mit before weiter zurückblättern.
before
query
string
nein
Die id der ältesten bereits vorhandenen Nachricht; liefert die Seite danach. Geben Sie das Feld next aus der vorherigen Antwort zurück. Ist nextnull, haben Sie alles.
Das Postfach wurde gelesen. Ein leeres Postfach ist ein 200 mit count: 0, niemals ein 404. next trägt den Cursor für die nächste Seite oder null am Ende. alias ist eine zweite Adresse, die hierher zustellt und nichts über diese verrät — geben Sie ihn statt address an ein Formular weiter; wer ihn hat, sieht immer ein leeres Postfach. Er ist stabil, kostenlos, und wird auch für Premium-Adressen zurückgegeben.
400
Die Adresse ist fehlerhaft, oder before ist keine Nachrichten-ID.
400
address fehlt oder ist keine gültige Adresse.
401
Ein API-Schlüssel wurde gesendet und ist unbekannt oder widerrufen. Ein falscher Schlüssel wird auf jeder Domain abgelehnt; die öffentlichen Domains brauchen keinen.
402
Nur im Premium-Pool: Das Kontingent des Tarifs ist aufgebraucht — quota_reached, oder overage_cap / overage_funds, wenn Mehrverbrauch eingeschaltet ist. Bereits gehaltene Adressen funktionieren weiter.
403
Nur im Premium-Pool: Ein anderer Abonnent hält diese Adresse (address_taken).
404
Diese Domain wird hier nicht gehostet — MX-Eintrag prüfen. Eine Premium-Pool-Domain, die ohne einen Schlüssel aus einem bezahlten Tarif gelesen wird, antwortet absichtlich genau das.
429
Ratenlimit überschritten. Erneut versuchen nach der Verzögerung in Retry-After.
GET/api/v1/message/{id}
Header, der Klartext-Teil, der HTML-Teil und alle Anhänge.
Parameter
Name
Eingabe
Typ
Erforderlich
Beschreibung
id
path
string
ja
Die vom Listenaufruf zurückgegebene Nachrichten-ID.
mailbox
query
string
ja
Die Adresse, an die die Nachricht zugestellt wurde.
Gelöscht. Der Aufruf ist idempotent: zweimaliges Löschen antwortet weiterhin mit 200.
400
mailbox fehlt oder ist ungültig.
404
Keine solche Nachricht in diesem Postfach.
429
Ratenlimit überschritten.
Anhänge
Jede Nachricht listet ihre Anhänge mit einer fertigen URL. Rufen Sie sie mit
derselben Autorisierung wie die Nachricht selbst ab.
GET /api/v1/attachment/{id}?mailbox={address}
Es antwortet immer mit application/octet-stream und
Content-Disposition: attachment, unabhängig davon, wie der Absender es bezeichnet hat. Das ist Absicht: Würde man
fremdes text/html unverändert zurückgeben, könnte ein Anhang als Seite auf diesem
Origin ausgeführt werden. Der tatsächliche Typ steht im Nachrichten-JSON, wo er
Daten und keine Anweisung ist.
Fehler
Jeder Fehler ist JSON mit denselben zwei Feldern, sodass ein Client sie
an einer einzigen Stelle behandelt. Der Status trägt die Kategorie, error ist ein
stabiler, maschinenlesbarer Slug, und message ist für Menschen gedacht und
kann jederzeit umformuliert werden.
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "invalid_address",
"message": "address must look like name@domain"
}
Verzweigen Sie niemals anhand von message. Die verwendeten Slugs sind invalid_address, bad_cursor, unknown_domain, not_found, rate_limited, daily_limit_reached, unauthorized und, nur im Premium-Pool, quota_reached, overage_cap, overage_funds, address_taken und address_limit.
Manche Fehler enthalten mehr als die zwei Felder: einen hint, der sagt, was zu tun ist, einen docs-Link, bei 404 und 429 einen premium_pool-Block mit dem Preis des Pools und wie man ihn freischaltet, und bei einem 429 wegen eines kostenlosen Limits einen upgrade-Block, der sagt, was ein bezahlter Tarif aufhebt — geschrieben für einen Assistenten, der den Body stellvertretend für jemanden liest, damit er die Option weitergeben kann, statt aufzugeben.
Ratenlimits
Kostenlos, ohne Schlüssel: 60 Anfragen pro Minute und 1.000 pro Tag, je IP-Adresse. Jeder Zugriff auf ein Postfach zählt — Auflisten, Lesen einer Nachricht, ihres HTML-Inhalts oder eines Anhangs, Löschen — und ebenso jeder Aufruf eines MCP-Tools. Der Tageszähler wird um 00:00 UTC zurückgesetzt.
Mit einem kostenlosen API-Schlüssel folgt dasselbe Kontingent Ihrem Konto statt Ihrer IP-Adresse — praktisch, wenn Ihre Aufrufe von wechselnden Adressen kommen, etwa von einem CI-Runner. Ein kostenloses Konto hat einen Schlüssel, und die Postfächer, die er liest, erscheinen in Ihren Postfächern. Kostenlosen Schlüssel anlegen
Innerhalb dieses Rahmens gilt ein Lesevorgang pro Sekunde und Adresse: Ein Postfach einmal pro Sekunde abzufragen ist der vorgesehene Rhythmus.
Bezahlte Tarife haben weder ein Minuten- noch ein Tageslimit. Senden Sie den Schlüssel eines bezahlten Tarifs als Authorization: Bearer, und es gilt nur noch die Rate pro Adresse Ihres Tarifs — 2, 3 oder 5 Anfragen pro Sekunde, auf jeder Domain, pro Konto gezählt. Premium gibt es schon ab $12,99 im Monat. Tarife ansehen
Das Postfach auf dieser Website belastet das kostenlose API-Kontingent nicht: Eine offen gelassene Seite prüft weiter auf neue Post, solange Sie sie brauchen.
Wird ein Limit überschritten, erhalten Sie 429 mit einem Retry-After-Header in ganzen Sekunden: rate_limited für das Limit pro Minute oder pro Adresse, daily_limit_reached für das Tageslimit, mit der verbleibenden Zeit bis Mitternacht UTC. Jede kostenlose Antwort zeigt Ihnen, wo Sie stehen: X-RateLimit-Remaining für die Minute, X-RateLimit-Daily-Remaining für den Tag.
Aufbewahrung
Eine Nachricht wird 5 Tage
nach ihrem Eintreffen gelöscht, gelesen oder nicht. Jede Nachricht trägt
expires_at, Sie müssen dieses Datum also nie selbst berechnen.
Es ist eine feste Grenze, keine Einstellung — kein Parameter verlängert sie. Muss eine Nachricht
das Zeitfenster überdauern, holen Sie sie ab und speichern Sie sie selbst.
Ihre eigene Domain
Richten Sie Ihren MX-Eintrag auf smtp.grabmail.io aus, und jede Adresse Ihrer Domain antwortet über dieselben Endpunkte — keine zweite API zu lernen, keine Registrierung und kein Schlüssel.
