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