REST-API-Dokumentation

GET/api/email/{domain}/{user}/

Rufen Sie eine paginierte Liste der E-Mails eines Benutzers ab. Listenantworten enthalten nur Metadaten (Nr body / html_body).

Parameter	Standort	Beschreibung
domain	Weg	E-Mail-Domäne, z.B. example.com
user	Weg	Benutzername, z.B. testuser
page	Abfrage, optional	Seitenzahl (Standard 1)
limit	Abfrage, optional	Elemente pro Seite (Standard 20, maximal 100)

curl -X GET "https://BASE_URL/api/email/example.com/testuser/?page=1&limit=20"

{
  "emails": [
    {
      "id": 123,
      "subject": "Welcome",
      "sender": "[email protected]",
      "date": "2026-09-30T10:30:00.000Z",
      "has_attachments": false,
      "size": 1234
    }
  ],
  "total": 5,
  "page": 1,
  "limit": 20,
  "has_more": false
}

GET/api/email/{domain}/{user}/{email_id}

Erhalten Sie die vollständigen Details einer E-Mail.

curl -X GET "https://BASE_URL/api/email/example.com/testuser/123"

DELETE/api/email/{domain}/{user}/{email_id}

Eine bestimmte E-Mail löschen.

curl -X DELETE "https://BASE_URL/api/email/example.com/testuser/123"

{ "status": "deleted" }

POST/api/add-domain/{domain}

Fügen Sie eine neue Domain hinzu oder aktualisieren Sie den Online-Status einer vorhandenen Domain. Die Domäne muss über einen MX-Eintrag verfügen, der auf den Hostnamen des Systems verweist, damit sie akzeptiert wird (Status added, is_online: true).

curl -X POST "https://BASE_URL/api/add-domain/newdomain.com"

// Erfolgreich hinzugefügt
{ "status": "added", "domain": "newdomain.com", "is_online": true }

// Vorhandene Domain: Status aktualisieren
{ "status": "updated", "domain": "newdomain.com", "is_online": false }

GET/api/all-domains/ & /api/random-domains/

Alle Online-Domains (privat, Token erforderlich):

curl -X GET "https://BASE_URL/api/all-domains/" \
  -H "X-Domain-Token: YOUR_TOKEN"

Zufällige Online-Domains (öffentlich):

curl -X GET "https://BASE_URL/api/random-domains/?limit=10"

{ "domains": ["domain1.com", "domain2.com"], "total": 2 }

GET/api/check-mx/{domain}

Überprüfen Sie, ob eine Domain über einen gültigen MX-Eintrag verfügt, der auf das System verweist.

curl -X GET "https://BASE_URL/api/check-mx/example.com"

{ "result": "online" }   // oder "offline"

Fehlerbehandlung

Code	Bedeutung
200	Erfolg
400	Ungültige Anfrage (z. B. fehlerhafte Domäne/E-Mail)
401	Fehlendes oder ungültiges Token für einen privaten Endpunkt
404	E-Mail nicht gefunden
429	Ratenlimit überschritten

{ "detail": "Domain not found" }

Wichtige Hinweise

• E-Mail-Adressen müssen das Format verwenden [email protected]
• Nur Domains mit gültigen MX-Einträgen haben den Status „online“.
• E-Mails und inaktive Domains werden danach automatisch gelöscht 3 Tagen
• Nur der Service erhält E-Mail – Senden und SMTP-Relay werden nicht unterstützt
• Die API wendet Ratenbegrenzungen pro IP an
• Für den Live-Service gilt die 3-tägige Aufbewahrungsfrist; Backups können Kopien länger aufbewahren. Eine dauerhafte Löschung aller Kopien ist zu diesem Zeitpunkt nicht garantiert.
• Posteingänge mit benutzerdefinierten Domains bleiben öffentlich und können von Drittanbieterdiensten blockiert werden. Für Annahme und Lieferung besteht keine Gewähr.