DE Sprache ändern
Postfach öffnen

API-Referenz

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 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.

Bei einer Domain, die Ihnen gehört, ist das Postfach privat, daher tragen Anfragen einen Schlüssel — er beweist, dass das Postfach Ihnen gehört. Der Schlüssel wird ausgestellt, wenn Sie Domain verifizieren, einmal angezeigt und hier nur als Hash gespeichert: 

Authorization: Bearer <your key>

Falscher oder fehlender Schlüssel bei einer privaten Domain ergibt 401 mit unauthorized. Schlüssel werden in konstanter Zeit verglichen, ein falscher braucht also genauso lange zur Ablehnung wie ein richtiger zur Annahme.

Endpunkte

GET /api/v1/mailbox

Alles, was an einer Adresse wartet, neueste zuerst. Diesen Aufruf pollt Ihre Testsuite.

Parameter

NameEingabeTypErforderlichBeschreibung
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 next null, haben Sie alles.

Beispiel

Postfach auflisten 
$ 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"
    }
  ]
}

Statuscodes

200
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.
400
Die Adresse ist fehlerhaft, oder before ist keine Nachrichten-ID.
400
address fehlt oder ist keine gültige Adresse.
404
Diese Domain wird hier nicht gehostet — MX-Eintrag prüfen.
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

NameEingabeTypErforderlichBeschreibung
id path string ja Die vom Listenaufruf zurückgegebene Nachrichten-ID.
mailbox query string ja Die Adresse, an die die Nachricht zugestellt wurde.

Beispiel

Eine Nachricht lesen 
$ 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": []
}

Statuscodes

200
Die Nachricht. html ist null, wenn der Absender nur reinen Text gesendet hat.
400
mailbox fehlt oder ist ungültig.
404
Keine solche Nachricht in diesem Postfach — oder ihre Aufbewahrungsfrist ist abgelaufen.
429
Ratenlimit überschritten.
DELETE /api/v1/message/{id}

Entfernt sie sofort, statt auf den Ablauf des Aufbewahrungszeitraums zu warten.

Parameter

NameEingabeTypErforderlichBeschreibung
id path string ja Die zu entfernende Nachricht.
mailbox query string ja Die Adresse, an die sie zugestellt wurde.

Beispiel

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

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

Statuscodes

200
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, unknown_domain, not_found und rate_limited.

Ratenlimits

Eine Anfrage pro Sekunde, pro Adresse. Ein Postfach einmal pro Sekunde abzufragen ist das vorgesehene Muster und wird nie gedrosselt.

Bei Überschreiten des Limits erhalten Sie 429 mit Retry-After in Sekunden. Es gibt kein Tageskontingent und kein Burst-Guthaben zu verwalten.

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 und jede Adresse Ihrer Domain antwortet über dieselben Endpunkte — keine zweite API zu lernen, und die Postfächer sind nur mit Ihrem Schlüssel lesbar.

Domain verbinden →