Verwendung der Automatisierungsproxys

Einleitung

Der BelWü-Kundeninfo-Server  bietet zur Verwaltung von E-Mail-Konten Funktionen an, die über die Möglichkeiten der Weboberfläche unseres Mail-Servers hinausgehen. Im Einzelnen sind das:

Neben der Weboberfläche des Kundeninfo-Servers stehen auch Automatisierungsproxys zur Verfügung, die es erlauben, diese Funktionen mittels eines Tools wie z. B. curl  direkt zu verwenden, was es ermöglicht, bestimmte Vorgänge auf dem eigenen System zu automatisieren (z. B. regelmäßiger Dump der E-Mail-Konten mittels Cron-Job). Wie das geht, wird im Folgenden beschrieben.

Hinweis: Diese Anleitung geht davon aus, dass Sie grundsätzlich mit der Verwendung der Tools Ihrer Wahl vertraut sind. Eine grundlegende Einführung in z. B. curl  oder Cron-Jobs würde den Rahmen dieses Dokuments deutlich sprengen.

Voraussetzungen

Wie auch für die Verwendung dieser Funktionen mithilfe der Weboberfläche des BelWü-Kundeninfo-Servers  wird für die Verwendung der Automatisierungsproxys ein gültiger Zugang zum Kundeninfoserver benötigt. Darüber hinaus braucht man den E-Mail-Admin-Zugang, der es erlaubt, die Mail-Konten der entsprechenden Domain auf unserem Mail-Server  zu verwalten (siehe hierzu auch den Artikel "Kurzanleitung zur Selbstverwaltung von E-Mail-Konten (Webadmin)").

In den Beispielen werden folgende fiktive Daten verwendet, die bei realen Aufrufen natürlich durch die echten Werte ersetzt werden müssen:
Benutzername Kundeninfo-Server ich
Passwort Kundeninfo-Server kdipw
Mail-Domain meine-mails.de
Benutzername Mail-Admin admin
Passwort Mail-Admin mapw

Anmerkung: Bei den Beispielpasswörtern handelt es sich um unsichere Passwörter, die der besseren Anschaulichkeit der Beispiele wegen so gewählt wurden. Bitte beachten Sie bei der Vergabe von Passwörten unsere Hinweise zur Wahl eines guten Passworts!

Aufruf der Proxys

Für jede der erweiterten Mail-Verwaltungsfunktionen steht ein eigener Automatisierungsproxy zur Verfügung. Deren Adressen sind:
listenbasiertes Löschen https://kundeninfo.belwue.de/myaccount/mail-delete/cgp_proxy.php
Gruppen verwalten https://kundeninfo.belwue.de/myaccount/mail-groups/cgp_proxy.php
Exportfunktion https://kundeninfo.belwue.de/myaccount/mail-export/cgp_proxy.php

Bei jedem Proxy-Aufruf müssen eine Reihe von Parametern mitgeliefert werden. Ein Teil der Parameter ist bei allen Proxys gleich, ein Teil bezieht sich auf die jeweilige Funktion eines Proxys und unterscheidet sich daher von den Parametern der anderen Proxys.

Folgende Parameter müssen bei jedem Proxy-Aufruf mitgegeben werden:

Name Beispielwert (s. o. ) Funktion
nick ich Benutzername Kundeninfo-Server
pw kdipw Passwort Kundeninfo-Server
domain meine-mails.de Mail-Domain
admin admin Benutzername Mail-Admin
password mapw Passwort Mail-Admin

Diese Parameter werden i. d. R. als sog. GET-Parameter direkt in der URL des Proxy-Aufrufs mit angegeben:

curl <Adresse des Proxys>?nick=ich\&pw=kdipw\&domain=meine-mails.de\&admin=admin\&password=mapw

Das <Adresse des Proxys> ist dabei natürlich durch die Adresse des gewünschten Proxys zu ersetzen (vgl. dazu auch die Beispiele weiter unten).

Die spezifischen Parameter für die einzelenen Funktionen werden im Folgenden bei der Beschreibung der jeweiligen Funktionen erklärt.

Hinweis: Testen Sie vielleicht zuerst die Funktion "Export der Konten, Gruppen und Mailing-Listen", um zu sehen, ob Sie alle Parameter korrekt angeben, denn dabei kann nicht versehentlich etwas "kaputtgehen".

Die Proxy-Aufrufe liefern i. d. R. eine Antwort in Form einer validen HTML5-Seite zurück, der entnommen werden kann, ob die Operation erfolgreich durchgeführt werden konnte bzw. was ggf. nicht geklappt hat. Ausnahmen von dieser Art der Antwort sind – falls zutreffend – bei der Detailbeschreibung der entsprechenden Funktion angegeben.

Eine Okay-Antwort kann z. B. so aussehen:

<html lang="de">
<head>
  <title>Mail-Konten löschen</title>
  <meta charset="utf-8">
</head>
<body>
<pre>

Account "mailKonto@meine-mails.de" deleted.

</pre>
</body>

Eine Fehlerantwort sieht z. B. so aus:

<html lang="de">
<head>
  <title>Mail-Konten löschen</title>
  <meta charset="utf-8">
</head>
<body>
<pre>
FEHLER:
Unable to delete "mailKonto@meine-mails.de": unknown user account

</pre>
</body>

oder so:

<html lang="de">
<head>
  <title>Mail-Konten löschen</title>
  <meta charset="utf-8">
</head>
<body>
<pre>
FEHLER:
No access for admin@meine-mails.de: incorrect password or account name
</pre>
</body>

Listenbasiertes Löschen von E-Mail-Konten

Zusätzlich zu den Parametern, die für alle Proxy-Aufrufe gelten, muss die Liste mit den zu löschenden Mailkonten übertragen werden. Die Kontenliste ist eine unformatierte Textdatei mit den Namen der zu löschenden Mailkonten – pro Zeile ein Name ohne Domainendung (also ohne das @meine-mails.de am Ende). Bitte beachten Sie, dass die Textdatei derzeit maximal 5000 Bytes groß sein darf.

Die Liste wird als File-Upload übertragen, der zugehörige Parameter heißt accList. Wenn die Datei, die die Liste enthält, z. B. liste.txt heißt, sieht der zugehörige Aufruf so aus:

curl -F 'accList=@liste.txt' https://kundeninfo.belwue.de/myaccount/mail-delete/cgp_proxy.php?nick=ich\&pw=kdipw\&domain=meine-mails.de\&admin=admin\&password=mapw

Listenbasiertes Verwalten von Mail-Gruppen

Zur Bearbeitung einer E-Mail-Gruppe braucht es drei zusätzliche Parameter: den Namen und die Beschreibung der Gruppe sowie eine unformatierte Textdatei mit den E-Mail-Adressen der Teilnehmer – pro Zeile eine Adresse. Steht vor einer Adresse ein Minuszeichen, wird diese Adresse aus der Gruppe entfernt. Falls die angegebene Gruppe noch nicht existiert, wird sie neu angelegt.

Der Inhalt der Listendatei kann z. B. so aussehen:

user1
user2@external.domain.com
-user3

Der Parameter für den Gruppennamen heißt group, der für die Gruppenbeschreibung descr. Die Liste wird als File-Upload übertragen, der zugehörige Parameter heißt memList. Wenn die Gruppe meineGruppe angelegt/geändert werden soll, die Beschreibung Gruppenbeschreibung ist und der Dateiname liste.txt lautet, sieht der zugehörige Aufruf so aus:

curl -F 'memList=@liste.txt' https://kundeninfo.belwue.de/myaccount/mail-groups/cgp_proxy.php?nick=ich\&pw=kdipw\&domain=meine-mails.de\&admin=admin\&password=mapw\&group=meineGruppe\&descr=Gruppenbeschreibung

Beachten Sie bitte, dass Leerschritte und ggf. andere "exotische" Zeichen, die in Parameterwerten enthalten sein sollen, beim Aufruf URL-encodiert werden müssen, ein Leerzeichen also als %20 etc.

Export der Konten, Gruppen und Mailing-Listen

Für den Export der Konten, Gruppen und Mailing-Listen muss als zusätzlicher Parameter das Format angegeben werden, in dem der Export erfolgen soll. Der Parameter dafür heißt format. Folgende Werte können für ihn angegeben werden:

Wert Export-Format
csv CSV
csvexp CSV incl. Verteilerlisten
vcard vCard

Um also z. B. einen CSV-Export incl. Verteilerlisten zu erhalten, sieht der Aufruf so aus:

curl https://kundeninfo.belwue.de/myaccount/mail-export/cgp_proxy.php?nick=ich\&pw=kdipw\&domain=meine-mails.de\&admin=admin\&password=mapw\&format=csvexp

Im Erfolgsfall liefert diese Funktion als Antwort eine Datei im angeforderten Format zurück. Im Fehlerfall besteht die Antwort aus einer validen HTML5-Seite, die einen Hinweis darauf gibt, was nicht geklappt hat (s. o. bei der allgemeinen Beschreibung der Antworten).