REST API · v1

Wegwerf-Postfächer per HTTP.

Alles, was die Oberfläche kann, geht auch per API – ideal für automatisierte Tests von Registrierungs- und Bestätigungs-Flows. Authentifiziert wird mit deinem Access Key als Bearer-Token. Antworten sind JSON.

Authentifizierung

Jede Anfrage außer /config und POST /accounts benötigt den Header:

Authorization: Bearer SHDW-XXXX-XXXX-XXXX-XXXX-XXXX

Schnellstart

# 1. Key + erste Adresse erzeugen
curl -X POST /api/accounts

# 2. Nachrichten einer Adresse abrufen
curl /api/addresses/ADDRESS_ID/messages \
  -H "Authorization: Bearer $KEY"

# 3. Eine Nachricht vollständig lesen
curl /api/messages/MESSAGE_ID \
  -H "Authorization: Bearer $KEY"

Endpunkte

GET/api/configVerfügbare Domains, Aufbewahrungsdauer und Limits.

POST/api/accountsErzeugt einen neuen Access Key samt erster Adresse. Der Key wird nur dieses eine Mal ausgegeben.

{ "token": "SHDW-7K2M-…", "address": { "id": "c_e0TQnt8i7_", "address": "quiet-raven-4821@domain", … } }

GET/api/meAlle Adressen des Keys inkl. Anzahl ungelesener Nachrichten.

DELETE/api/meLöscht Key, Adressen und Nachrichten sofort und endgültig.

POST/api/addressesNeue Adresse. Ohne local wird ein zufälliger Name erzeugt.

{ "local": "mein.test", "domain": "domain" }

DELETE/api/addresses/:idLöscht eine Adresse samt Nachrichten. Die Adresse wird dauerhaft gesperrt.

GET/api/addresses/:id/messagesNachrichtenliste (Absender, Betreff, Vorschau, Ablaufzeit), neueste zuerst.

DELETE/api/addresses/:id/messagesLeert den Posteingang einer Adresse.

GET/api/messages/:idVollständige Nachricht mit text, bereinigtem html und Anhangsliste. Markiert sie als gelesen.

DELETE/api/messages/:idLöscht eine Nachricht.

GET/api/messages/:id/attachments/:idxLädt einen Anhang als Binärdatei herunter.

GET/api/eventsServer-Sent-Events-Stream. Sendet message-Events, sobald eine Mail eingeht.

event: message
data: {"addressId":"c_e0TQnt8i7_","messageId":"dne3WZ9clvrrcUxG"}

Limits

Max. 10 Adressen pro Key · Nachrichten werden nach 24 h gelöscht · max. 10 MB pro Mail · inaktive Keys verfallen nach 30 Tagen · 300 API-Anfragen pro Minute. Bei Überschreitung antwortet die API mit 429 und Retry-After.

Fehler haben immer die Form { "error": "Beschreibung" } mit passendem HTTP-Status (400, 401, 404, 409, 429).