E-Mail-Adressen
GET /email-addresses
Liefert eine Liste aller E-Mail-Adressen für den aktuellen Kunden.
Es ist möglich diese Liste nach konkreten Adressen zu filtern:
GET /email-addresses?filter[address]=info@beispielkunde.de
Sie können sowohl den filter[address]
-Parameter mehrfach anwenden, als auch mehrere Adressen durch Kommas trennen.
Falls Sie die ID einer Adresse haben, können sie sie auch direkt abrufen:
GET /email-addresses/{id}
Es gibt zwei Sorten von E-Mail-Adressen:
mailbox
: Die E-Mails lagern in einem Postfach auf unseren Servern und werden mittels IMAP oder Webmail abgerufen. Optional ist zusätzlich eine Weiterleitung möglich.forward
: Die E-Mails werden ausschließlich weitergeleitet.
Je nach Typ enthalten die Details Zusatzinformationen, wie zum Beispiel Postfach-Quotas.
Anlegen von Adressen
POST /email-addresses
Erstellt eine neue E-Mail-Adresse anhand des POST-Bodys.
Mögliche Felder:
address
: Die Adresse die Sie anlegen möchten. Sie darf nicht existieren und die Domain muss Teil Ihres Kundenkontos sein.address_type
: Mussmailbox
oderforward
sein.description
: Optional, Default:null
. Beschreibung der Adresse die im Kundenmenü und in der API angezeigt wird.antispam
: Optional, Default:reject
. Die Spamschutzeinstellungen für die neue E-Mail-Adresse. Muss eines vonreject
,junk-folder
(nur Mailboxen),subject-rewrite
odernone
sein. Wir empfehlen dringend, diese Einstellung nicht zu ändern.forward_to
: Optional für Mailboxen, jedoch Pflicht für Weiterleitungen. Eine Liste von E-Mail-Adressen, an die jede E-Mail weitergeleitet wird.
Postfächer
Ein Beispiel für einen POST-Body, der ein Postfach mit der E-Mail-Adresse „postfach@beispielkunde.info“ anlegt:
{
"data": {
"type": "email-address",
"attributes": {
"address_type": "mailbox",
"description": "Eine freiwillige Beschreibung.",
"address": "postfach@beispielkunde.info",
"forward_to": []
}
}
}
Ein sicheres Passwort für das Postfach wird automatisch generiert und mit der Bestätigung zurückgegeben.
Weiterleitungen
Ein Beispiel für einen POST-Body, der eine E-Mail-Adresse „weiterleitung@beispielkunde.info“ anlegt, dessen E-Mails an „postfach1@beispielkunde.info” und „postfach2@beispielkunde.info” weitergeleitet werden:
{
"data": {
"type": "email-address",
"attributes": {
"address_type": "forward",
"description": "Eine freiwillige Beschreibung.",
"address": "weiterleitung@beispielkunde.info",
"forward_to": [
"postfach1@beispielkunde.info",
"postfach2@beispielkunde.info"
]
}
}
}
Ändern von Adressen
PATCH /email-addresses/{id}
Erlaubt die Manipulation von existierenden Adressen.
Postfachpasswörter
Folgender Body für PATCH /email-addresses/42
ändert das Passwort auf "lieber laenger, als kuerzer":
{
"data": {
"type": "email-address",
"id": "42",
"attributes": {
"password": "lieber laenger, als kuerzer"
}
}
}
Bitte beachten Sie, dass zu Ihrer Sicherheit strikte Anforderungen an die Passwörter gestellt werden:
- Mindestens 16 Zeichen lang.
- Mindestens 10 davon müssen sich unterscheiden (groß/klein reicht nicht).
- Gültige Zeichen sind:
- alle Buchstaben ohne Umlaute (A–Z und a–z)
- alle Zahlen (0–9)
- das Leerzeichen
- die folgenden Sonderzeichen:
.
,,
,$
,/
,_
,*
,!
,#
,@
,+
,-
, und&
.
- Weder der Nutzername noch die Domain dürfen in irgendeiner Form im Passwort vorkommen.
- Die Wörter "Variomedia", "vrmd", "Securehost", "Password" und "Passwort" dürfen nicht im Passwort vorkommen.
- Das Beispielpasswort von oben ist nicht zulässig.
- Zeichenfolgen wie
qwert
oderasdf
dürfen nicht im Passwort vorkommen. - Zusätzlich wird überprüft, dass das Passwort nicht in einer der gängigen Listen von geleakten Passwörtern auftaucht.
Sollten Sie einfach nur ein neues, sicheres Passwort wünschen, benutzen Sie den folgenden Endpunkt:
POST /email-addresses/{id}/password
Das Postfach erhält ein neues, zufällig generiertes Passwort und es wird im Response-Body zurückgeliefert.
Zusätzliche Weiterleitungen
Sowohl Postfächer, als auch Weiterleitungen erlauben es, zusätzliche Empfänger zu definieren (/data/attributes/forward_to
).
Als Komfortfunktion können Sie diese Weiterleitungen einzeln von Hand hinzufügen:
POST /email-addresses/{id}/forward-to/weiterleitungsziel@beispielkunde.info
und entfernen:
DELETE /email-addresses/{id}/forward-to/weiterleitungsziel@beispielkunde.info
Autoresponder
Ändern des Textes
Um den Autoresponder-Text für die Adresse mit der ID 42 zu ändern senden sie den folgenden Body an PATCH /email-addresses/42
:
{
"data": {
"type": "email-address",
"id": "42",
"attributes": {
"autoresponder": {"text": "Ich bin im Urlaub."}
}
}
}
Bitte beachten Sie, dass Sie nur Zeichen verwenden können, die in den Latin-1/ISO 8859-1-Zeichensatz passen: deutsche Umlaute gehen, Unicode-Zeichen wie “
jedoch leider nicht.
Aktivieren und deaktivieren
Das Aktivieren und Deaktivieren eines Autoresponders funktioniert analog zum Ändern des Textes:
{
"data": {
"type": "email-address",
"id": "42",
"attributes": {
"autoresponder": {"active": true}
}
}
}
Bitte beachten Sie, dass sie zum Setzen und Aktivieren zwei Requests benötigen, da nur ein Attribut pro Request geändert werden kann.
Beschreibung
{
"data": {
"type": "email-address",
"id": "42",
"attributes": {
"description": "Eine Beschreibung der E-Mailadresse."
}
}
}
Setzt die Beschreibung für eine E-Mailadresse. Wenn Sie die Beschreibung entfernen möchten, setzen Sie sie auf null
.
Spamschutz
Sie können PATCH
ebenfalls verwenden, um den Spamschutz zu ändern:
{
"data": {
"type": "email-address",
"id": "42",
"attributes": {
"antispam": "reject"
}
}
}
Die gültigen Werte entnehmen Sie bitte von oben.
Löschen von Adressen
DELETE /email-addresses/{id}
Erlaubt es Ihnen ein Postfach oder eine Weiterleitung permanent zu löschen.