API-URL und Zeichensatz
Alle Requests werden per POST an folgende URL gesendet:
https://api.mailbox.org/v1/
Der verwendete Zeichensatz ist UTF-8.
JSON-RPC 2.0
Die Requests und Responses der API entsprechen der JSON-RPC 2.0 Spezifikation.
Authentifizierung
Es ist möglich, anonyme Requests und authentifizierte Requests an die API zu senden.
Ein authentifizierter Request enthält einen HTTP-Header mit einer gültigen Auth-ID.
Auth-ID erhalten
Mit der Methode auth und einem Benutzernamen und einem Passwort als Parameter kann eine Auth-ID von
der API angefordert werden. Diese ID kann auch als Session-ID verstanden werden.
Diese ID ist 20 Minuten gültig. Die Lebensdauer wird bei jeder Benutzung jedoch wieder auf 20 Minuten aufgestockt.
Es wird außerdem das Auth-Level zurück gegeben. Für manche API-Methoden gibt es Mindest-Level.
Folgende Level sind verfügbar: admin, reseller, account, domain, mail, ftp
Auth-ID im HTTP-Header übertragen
Die ID wird vom API-Client im HTTP-Header HPLS-AUTH transportiert.
HPLS-AUTH: dlj3keZzTupJyX;KsSv57037ba615c926.43918213
Sollte eine Auth-ID nicht mehr gültig sein, so wird folgender Fehler zurück gegeben:
{
"jsonrpc":"2.0",
"error":{
"code":253,
"message":"Diese Auth-ID ist ung\u00fcltig"
},
"id":"1"
}Die Nutzung eines API-Clients erleichtert das Handling der Auth-ID.
API-Client
Für die einfache Bedienung der API stellen wir einen API-Client in PHP zur Verfügung.
Die aktuelleste Version des Clients ist unter folgender URL zum Download verfügbar:
https://api.mailbox.org/v1/client
Eine ausführlichere Dokumentation zum PHP-API-Client findet sich hier.
API-Clients in anderen Sprachen sind in Arbeit.
Context-ID
Ein Kontext beinhaltet Benutzer, Gruppen und Ressourcen (bspw. Meetingräume) mit deren Objekten. Daten wie beispielsweise Kalender oder Dateiordner können einfach mit anderen Benutzern aus demselben Kontext geteilt werden und sind in deren eigenem Account verfügbar. Für alle Benutzer außerhalb des Kontext wird stattdessen ein Link generiert und in einem separaten Tab / Fenster geöffnet.
Es ist möglich, eine oder mehrere Domains in einen Context zu platzieren, damit die Mailadressen dieser Domains miteinander Kalender und Adressbücher teilen können.
Fehlerauswertung
Die API gibt bei jedem Fehler einen Fehlercode zurück. Aktuell ist es so, dass dieser bspw. bei fehlenden Parametern, ungenau ist und nicht exakt zurück meldet, welcher Parameter fehlt.
Hier hilft derzeit nur die Überprüfung mit Hilfe der Dokumentation.
Wir arbeiten daran, dass Details zum Fehler in Zukunft im "data"-Objekt des Error-Objekts transportiert werden.
Domains hinzufügen
Die API prüft in den DNS-Daten Ihrer Domain, ob diese Domain bereits den mailbox.org-Sicherheitsschlüssel enthält. Ist alles okay, wird die Domain angelegt und ist ab sofort normal benutzbar.
Um eine Domain hinzuzufügen, muss ein von mailbox.org generierter Sicherheitsschlüssel im TXT-Record einer Subdomain der gewünschten Domain abgelegt werden.
Fehlt der DNS-Sicherheitsschlüssel, zum Beispiel weil Sie zum ersten Mal versuchen, diese Domain bei uns hinzufügen, wird die domain.add-Methode den Fehler 218 zurück geben:
{
"jsonrpc":"2.0",
"error":{
"code":218,
"message":"Der DNS-TXT-Record enth\u00e4lt nicht die richtigen Daten",
"data":{
"host":"5adc6e5a00bfa3f9fe1b1e14c73e03ad651b601c.domain.test",
"txt":"9dd07dc055aee1b63eb55f3e2874d5f253b3f643"
}
},
"id":"1"
}
Der im data-Objekt angegebene host ist eine neue Subdomain und der Wert txt ist ein TXT-Record für diese Subdomain. Erst wenn dieser Sicherheitsschlüssel gesetzt ist, können Sie die Domain hinzufügen.
Es muss in diesem Beispiel also:
- die Subdomain 5adc6e5a00bfa3f9fe1b1e14c73e03ad651b601c.domain.test angelegt werden
- als TXT-Record dieser Subdomain 9dd07dc055aee1b63eb55f3e2874d5f253b3f643 gesetzt werden
Achtung: Aufgrund der DNS-Cachezeiten kann es einige Stunden dauern, bis ein neu angelegter Sicherheitsschlüssel auch für unsere Systeme sichtbar ist!