Schnittstelle zur automatisierten Postfach-Konfiguration

Um mail-connect PRO Postfächer automatisiert verwalten zu können, bieten wir Ihnen eine API, also eine Schnittstelle an: Die mc-api.pl. Diese Schnittstelle können Sie in Ihrer Umgebung integrieren, um z.B. Postfächer neu einzurichten, zu löschen oder um Autoresponder zu verwalten.

Die mc-api.pl Schnittstelle steht für alle mail-connect PRO Postfächer zur Verfügung und muss nicht separat beauftragt oder freigeschaltet werden. Der Zugriff erfolgt ganz einfach über eine verschlüsselte HTTPS-Verbindung.

Adresse

API: https://portal.all-connect.net/cgi-bin/mc-api.pl
Beispiel-Formular: https://portal.all-connect.net/mc-api.html

Bedienung

Der Aufruf von mc-api.pl erfolgt ausschließlich per HTTP-POST und für jeden Aufruf inkl. Login-Daten als Domain-Administrator, z.B. postmaster@beispieldomain.eu (Felder "login" und "password").

Funktionen

Die API versteht folgende Aktionen (Feld "action"):

add-mailbox

Zweck: Neues Postfach anlegen

Input Feld: "user" (zwingend): Zu erstellende E-Mail Adresse

Input Feld: "newpassword" (optional): Zu setzendes Passwort, wenn Feld leer bleibt, erzeugt das System ein Passwort

Antworten: "FAILED", "OK" oder "OK: <neues kennwort>"

del-mailbox

Zweck: Postfach löschen

Input Feld: "user" (zwingend): Zu löschende E-Mail Adresse

Antworten: "FAILED", "OK"

set-mailbox-pw (war password-change)

Zweck: Passwort eines Postfachs ändern

Input Feld: "user" (zwingend): Zu ändernde E-Mail Adresse

Input Feld: "newpassword" (zwingend): Zu setzendes Passwort

Antworten: "FAILED", "OK"

set-forward

Zweck: "E-Mail Weiterleitung" aktivieren und Weiterleitungsziel setzen

Input Feld: "user" (zwingend): Zu ändernde E-Mail Adresse

Input Feld: "forward" (zwingend): Ziel-Adresse für Weiterleitung

Antworten: "FAILED", "OK"

set-forward-localcopy

Zweck: "E-Mail Weiterleitung" und "Lokale Kopie speichern" aktivieren und Weiterleitungsziel setzen

Input Feld: "user" (zwingend): Zu ändernde E-Mail Adresse

Input Feld: "forward" (zwingend): Ziel-Adresse für Weiterleitung

Antworten: "FAILED", "OK"

del-forward

Zweck: "E-Mail Weiterleitung" und "Lokale Kopie speichern" deaktivieren und Weiterleitungsziel löschen

Input Feld: "user" (zwingend): Zu ändernde E-Mail Adresse

Antworten: "FAILED", "OK"

set-autoreply

Zweck: "Autoresponder" dauerhaft aktivieren und Antworttext setzen

Input Feld: "user" (zwingend): Zu ändernde E-Mail Adresse

Input Feld: "text" (zwingend): Antworttext

Antworten: "FAILED", "OK"

set-autoreply-timed

Zweck: "Autoresponder" zeitweise aktivieren und Antworttext setzen

Input Feld: "user" (zwingend): Zu ändernde E-Mail Adresse

Input Feld: "from" (zwingend): Datum ab wann Autoresponder aktiv sein soll (erlaubte Formate DD.MM.YYYY oder YYYY-DD-MM, Beispiele 15.09.2019 bzw. 2019-05-28)

Input Feld: "till" (zwingend): Datum bis wann Autoresponder aktiv sein soll (Formate wie "from"-Feld; Format zwischen "from"- und "till"-Feld darf nicht gemischt werden!)

Input Feld: "text" (zwingend): Antworttext

Antworten: "FAILED", "OK"

del-autoreply

Zweck: "Autoresponder" deaktivieren und Antworttext löschen

Input Feld: "user" (zwingend): Zu ändernde E-Mail Adresse

Input Feld: "text" (zwingend): Antworttext

Antworten: "FAILED", "OK"

get-mailbox-config

Zweck: Postfach Konfiguration abfragen

Input Feld: "user" (zwingend): Abzufragende E-Mail Adresse

Antworten: "FAILED", Beispiel für Config

<userconfig>
<quota>1000</quota>
<av>1</av>
<forwardsavelocal>0</forwardsavelocal>
<maxmsgsize>30</maxmsgsize>
<asrefuse>5</asrefuse>
<quotausage>133</quotausage>
<forward>0</forward>
<quotawarningthreshold></quotawarningthreshold>
<autorespondertext>Ich befinde mich zur Zeit im Urlaub.</autorespondertext>
<forwardto>unterwegs@example.com</forwardto>
<lastlogin_from>imap@mua02</lastlogin_from>
<lastlogin_time>2013-01-16 10:09:37</lastlogin_time>
<astag>3</astag>
<autoresponder>0</autoresponder>
<realname>My Realname</realname>
<as>1</as>
<enabled>1</enabled>
</userconfig>

Hinweis: zur Postfach Config XML: Bitte implementieren Sie das Einlesen der XML so, dass jederzeit Felder hinzugefügt werden können. Technisch bleiben Änderungen (und Sortierung) am XML zu jederzeit vorbehalten.

Feld-Bedeutungen (sofern nicht selbsterklärend):

• enabled = Status Konto: 1 = aktiv, 0 = inaktiv
• quota = Postfach-Speicherlimit, 0 = unlimited
• quotawarningthreshold = Prozentwert als Integer, ab dem Benutzer einen Warnhinweis zur Speicherauslastung erhält; 0 = Standardwerte für 75% - 94% je nach Gesamtgröße des Postfachs
• av = Anti-Virus: 1 = aktiv, 0 = inaktiv
• as = Anti-Spam: 1 = aktiv, 0 = inaktiv
• asrefuse = Punktwert Spamfilter für Abweisung
• astag = Punktwert Spamfilter für Header-Markierung
• quotausage = Verwendeter Speicherplatz in MB
• forward = E-Mail Weiterleitung: 1 = aktiv, 0 = inaktiv
• forwardto = Weiterleitungsziel
• forwardsavelocal: Lokale E-Mail-Kopie speichern, wenn Weiterleitung aktiv: 1 = aktiv, 0 = inaktiv
• autoresponder = Automatische E-Mail-Beantwortung: 1 = aktiv, 0 = inaktiv

Passwort Encoding für Sonderzeichen

Grundsätzlich dürfen die Passwörter alle Sonderzeichen enthalten (= sowohl das PW für den autorisierten Login, als auch das (optionale) PW, welches für das zu editierende Konto-Objekt gesetzt werden soll). Um sicher zu stellen, dass die PW-Strings richtig weiterverarbeitet werden, wenn Sonderzeichen enthalten sind, müssen diese zunächst browserseitig immer in BASE64 encodiert und dann URL-safe übermittelt werden.

Dazu sind clientseitig folgende Encodingfunktionen einzubauen (wahlweise in PHP oder JS):

Decode / Encode in php

    function base64url_encode($data) {
        return rtrim(strtr(base64_encode($data), '+/', '-_'), '=');
    }

    function base64url_decode($data) {
        return base64_decode(strtr($data, '-_', '+/'));
    }

Encode in Javascript

function btoahtml(data) {
    var thisdata = btoa(data);
    thisdata = thisdata.replace('-', '+');
    thisdata = thisdata.replace('/', '_');
    thisdata = thisdata.replace(/=+$/, '');
    return thisdata;
}

Return Codes

Im Grundsatz erhalten Sie die Return-Codes in Form eines HTTP-Status Codes:

• 200: Der Aufruf hat funktioniert und der genaue Status wird von der Schnittstelle als HTML-Ausgabe zurückgegeben.
• 503: Die Schnittstelle selbst arbeitet fehlerfrei, jedoch konnte der Aufruf nicht ausgeführt werden, weil ein interner Prozess an der Datenbank dies verhindert hat.
• 50x: Sonstige Fehler.

Generell empfehlen wir, bei Fehlern (Status Codes 5xx) den Aufruf wenig später noch einmal zu wiederholen.

Insb. im Fall eines 503-Codes kann dies durch interne Wartungsprozesse veranlasst sein (z.B. Backup der Datenbank, Echtzeit-Synchronisierung mit E-Mail-Diensten, parallele Konfigurationen über das Kunden-Portal auf die selben Postfach- oder Mailserver-Objekte). In diesem Fall hilft es meist, den Aufruf ca. 15 - 30 Min. später noch einmal über eine Queue zu wiederholen.

Im Falle sonstiger Fehler hilft Ihnen unser mail-connect Support weiter, den Fehler auf der Server-Seite weiter einzugrenzen. Bitte beachten Sie, dass unser Support nicht für die Fehlerbehebung auf der Client-Seite zuständig ist.

Beispiele mit curl

Folgendes Beispiel basiert auf einen bash-Script, wie es unter Linux oder Mac direkt verarbeitet werden kann:

#!/bin/bash

function base64url_encode(){
    local HASH=$1
    local RESULT=`echo -n ${HASH} | base64 | sed -r 's/-/+/g' | sed -r 's/\//_/g' | sed -r 's/=+$//g'`
    echo $RESULT
}

LOGIN="postmaster@beispieldomain.eu"
PW="xxx"
PW=`base64url_encode ${PW}`
USER="mailbox@beispieldomain.eu"
URL="https://admin.mail-connect.net/cgi-bin/mc-api.pl"

echo -n "Testing add-mailbox: "
RESULT=`curl -s --data-urlencode login=$LOGIN --data-urlencode password=$PW --data-urlencode action="add-mailbox" --data-urlencode user=$USER --data-urlencode newpassword="Test234" $URL`
echo $RESULT

echo -n "Testing get-mailbox-config: "
RESULT=`curl -s --data-urlencode login=$LOGIN --data-urlencode password=$PW --data-urlencode action="get-mailbox-config" --data-urlencode user=$USER $URL`
echo $RESULT

echo -n "Testing set-mailbox-pw: "
NEWPASSWORD=`base64url_encode "Test"`
RESULT=`curl -s --data-urlencode login=$LOGIN --data-urlencode password=$PW --data-urlencode action="set-mailbox-pw" --data-urlencode user=$USER --data-urlencode newpassword=${NEWPASSWORD} $URL`
echo $RESULT

echo -n "Testing set-forward: "
RESULT=`curl -s --data-urlencode login=$LOGIN --data-urlencode password=$PW --data-urlencode action="set-forward" --data-urlencode user=$USER --data-urlencode forward="martin@waschbuesch.de" $URL`
echo $RESULT

echo -n "Testing set-forward-localcopy: "
RESULT=`curl -s --data-urlencode login=$LOGIN --data-urlencode password=$PW --data-urlencode action="set-forward-localcopy" --data-urlencode user=$USER --data-urlencode forward="martin@waschbuesch.de" $URL`
echo $RESULT

echo -n "Testing set-autoreply: "
RESULT=`curl -s --data-urlencode login=$LOGIN --data-urlencode password=$PW --data-urlencode action="set-autoreply" --data-urlencode user=$USER --data-urlencode text="Ich bin nicht da.
Ich bin nicht da.
Ich bin nicht da.
Ich bin nicht da.
Ich bin nicht da." $URL`
echo $RESULT

echo -n "Testing set-autoreply-timed: "
RESULT=`curl -s --data-urlencode login=$LOGIN --data-urlencode password=$PW --data-urlencode action="set-autoreply-timed" --data-urlencode user=$USER --data-urlencode text="Ich bin nicht da.
Ich bin nicht da.
Ich bin nicht da.
Ich bin nicht da.
Ich bin nicht da." --data-urlencode from="13.08.2013" --data-urlencode till="31.08.2013" $URL`
echo $RESULT

echo -n "Testing set-mailbox-pw: "
RESULT=`curl -s --data-urlencode login=$LOGIN --data-urlencode password=$PW --data-urlencode action="set-mailbox-pw" --data-urlencode user=$USER --data-urlencode newpassword="Test" $URL`
echo $RESULT

echo -n "Retesting get-mailbox-config: "
RESULT=`curl -s --data-urlencode login=$LOGIN --data-urlencode password=$PW --data-urlencode action="get-mailbox-config" --data-urlencode user=$USER $URL`
echo $RESULT

echo -n "Testing del-forward: "
RESULT=`curl -s --data-urlencode login=$LOGIN --data-urlencode password=$PW --data-urlencode action="del-forward" --data-urlencode user=$USER $URL`
echo $RESULT

echo -n "Testing del-autoreply: "
RESULT=`curl -s --data-urlencode login=$LOGIN --data-urlencode password=$PW --data-urlencode action="del-autoreply" --data-urlencode user=$USER $URL`
echo $RESULT

echo -n "Testing del-mailbox: "
RESULT=`curl -s --data-urlencode login=$LOGIN --data-urlencode password=$PW --data-urlencode action="del-mailbox" --data-urlencode user=$USER $URL`
echo $RESULT