API-Referenz

Ü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

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.

Ein Fall trägt weiterhin einen Header: Eine Domain, die wir auf Anfrage geschlossen haben, wird mit Authorization: Bearer <key> gelesen, und ein falscher oder fehlender Schlüssel ergibt 401 mit unauthorized. Schlüssel werden in konstanter Zeit verglichen, ein falscher braucht also genauso lange zur Ablehnung wie ein richtiger zur Annahme.

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 92 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 gültigen Schlüssel antwortet dieselbe Anfrage 402 oder 403 — nie mit einem Postfach.

# 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"

Die öffentlichen Domains und Ihre eigenen bleiben in jedem Tarif kostenlos, schlüssellos und unbegrenzt — auch im kostenlosen. Kontingente zählen nur Nachrichten, die im Premium-Pool eintreffen. Tarife und Preise stehen auf die Tarifseite.

Endpunkte

$ 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"
}

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 aus, und jede Adresse Ihrer Domain antwortet über dieselben Endpunkte — keine zweite API zu lernen, keine Registrierung und kein Schlüssel.

Domain verbinden →