E-Mail-Adressen

Es gibt zwei Sorten von E-Mail-Adressen:

mailbox: Die E-Mails lagern in einem Postfach auf unseren Servern und werden mittels IMAP, POP3 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.

GET /email-addresses

Liefert eine Liste aller E-Mail-Adressen für den aktuellen Kunden.

Mögliche Filter:

package_id: Paket
address: vollständige E-Mail-Adresse
domain: Domainteil der Adresse; Subdomains werden nicht unterstützt.

GET /email-addresses/{id}

Liefert Details zur E-Mail-Adresse mit der ID {id}.

Erstellen

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.
password: Optional, nur erlaubt für Mailboxen. Erlaubt das Setzen eines eigenen Passworts beim Anlegen der Mailbox. Bitte beachten Sie die dokumentierten Anforderungen an Passwörter.

Sollten Sie das Feld frei lassen (empfohlen), wird ein sicheres Passwort erstellt und mit der Bestätigung zurückgegeben.

Postfächer

Ein Beispiel für einen POST-Body, der ein Postfach mit der E-Mail-Adresse „postfach@beispielkunde.info“ anlegt, das Spam in einen speziellen Ordner sortiert:

{
  "data": {
    "type": "email-address",
    "attributes": {
      "address_type": "mailbox",
      "description": "Eine freiwillige Beschreibung.",
      "address": "postfach@beispielkunde.info",
      "forward_to": [],
      "antispam": "junk-folder"
    }
  }
}

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

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)
- alle Sonderzeichen aus der OWASP-Liste.
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 Aktivierung und Deaktivierung

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

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

beziehungsweise:

{
  "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 in den Beispielen oben demonstriert.

Um eine automatische (De-)aktivierung zu entfernen, benutzen Sie null als Wert für activates bzw. expires.

Bitte beachten Sie, dass derzeit nur ein Attribut pro Request geändert werden kann. Entsprechend kann es sein, dass Sie insgesamt bis zu vier 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

DELETE /email-addresses/{id}

Erlaubt es Ihnen ein Postfach oder eine Weiterleitung permanent zu löschen.

Variomedia Kunden-API