Schnittstelle zur automatisierten Postfach-Konfiguration

Aus all-connect Hilfe-Center
Zur Navigation springen Zur Suche springen


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 am XML zu jederzeit vorbehalten.

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;
}

Beispiel mit curl

#!/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
Abgerufen von „https://hilfe.all-connect.net/index.php?title=Schnittstelle_zur_automatisierten_Postfach-Konfiguration&oldid=3080“