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: Muss mailbox oder forward 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 von reject, junk-folder (nur Mailboxen), subject-rewrite oder none 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.

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"
      ]
    }
  }
}

Manipulation von Adressen

PATCH /email-addresses/{id}

Erlaubt die Manipulation von existierenden Adressen. Bitte beachten Sie, dass die ID in der URL und das id-Feld im Body identisch sein müssen.

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 oder asdf 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.

Application Passwords

Sie können mittels

POST /email-addresses/{id}/application-passwords

Sich ein neues Application Password zurückgeben lassen. Im Body müssen Sie die Attribute device und application setzen. Diese sind frei wählbar, dürfen jedoch nicht leer sein:

{
  "data": {
    "type": "application-password",
    "attributes": {
      "device": "Mobiltelefon",
      "application": "Mail"
    }
  }
}

Application Passwords können mit ihrer ID gelöscht werden:

DELETE /email-addresses/{address-id}/application-passwords/{application-password-id}

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."}
    }
  }
}

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

Automatische Deaktivierung

Auf die gleicher Art können Sie ein Datum hinzufügen, an dem Ihr Autoresponder automatisch kurz nach Mitternacht deutscher Zeit deaktiviert wird:

{
  "data": {
    "type": "email-address",
    "id": "42",
    "attributes": {
      "autoresponder": {"expires": "2020-03-06"}
    }
  }
}

Bitte verwenden Sie ausschließlich das ISO 8609-Format für das Datum, wie im Beispiel oben demonstriert.

Um eine automatische Deaktivierung zu entfernen, benutzen Sie null als Wert für expires.

Bitte beachten Sie, dass derzeit nur ein Attribut pro Request geändert werden kann. Entsprechend kann es sein, dass Sie insgesamt bis zu drei Requests brauchen, um Ihren Autoresponder zu konfigurieren.

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.

Variomedia Kunden-API