Schnittstelle zur automatisierten Postfach-Konfiguration: Unterschied zwischen den Versionen
Zur Navigation springen
Zur Suche springen
Mhe (Diskussion | Beiträge) |
Mhe (Diskussion | Beiträge) |
||
| Zeile 127: | Zeile 127: | ||
==Beispiel mit ''curl''== | ==Beispiel mit ''curl''== | ||
<pre> | <pre> | ||
#!/bin/bash | #!/bin/bash | ||
Version vom 10. Dezember 2020, 11:52 Uhr
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;
}
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