Variomedia Kunden-API

Unsere Kunden-API ermöglicht es allen Kunden wiederkehrende Vorgänge wie die Verwaltung von DNS-Einträgen oder das Anlegen von E-Mail-Adressen zu automatisieren.

Die API orientiert sich an der JSON:API-Spezifikation. Authentifizierung erfolgt über API Tokens, die für einzelne Kundenkontakte freigeschaltet werden müssen.

Unsere FAQ enthält praktische Beispiele (zum Beispiel Let’s Encrypt / certbot-Integration) und weitere Informationen.

Der Zugang muss manuell freigeschaltet werden. Bitte wenden Sie sich an die Kundenbetreuung – wir stellen Ihnen sehr gern einen Token aus.

Informationen zu unserer alten Reseller-API finden Sie unter /docs/legacy. Die alten API-Endpunkte funktionieren wie gewohnt und werden solange betrieben, bis die neue API volle Funktionsparität bietet.

Änderungen

2024-09-13

Reseller können nun Ihre Tarife einsehen.

2024-08-19

Reseller können nun ihren Kunden externe Kundennummern zuweisen und löschen.

2024-07-05

Reseller können nun Kunden den Zugang zum Kundenmenü (ent-)sperren.

2024-03-15

Der E-Mail-Adressen-Endpunkt zeigt nun auch die Belegung für den Open-Xchange App Drive-Dateispeicher an.

2022-10-11

Es ist nun möglich ein Startdatum für E-Mail-Autoresponder zu setzen.

2022-05-20

Die Liste der gültigen Zeichen für E-Mail-Postfachpasswörter wurde auf alle von der OWASP empfohlene erweitert.

2021-11-04

Subdomains können nun nach Domains gefiltert werden.

2021-05-27

Es ist nun unter Einschränkungen möglich, Catch-All-E-Mailadressen (default@domain.de) anzulegen.

2021-03-12

Es ist nun möglich beim Anlegen von E-Mail-Postfächern ein eigenes Passwort anzugeben.

2020-12-01

Datenbanken zeigen nun auch Ihren Verbrauch an, der täglich aktualisiert wird.

2020-10-08

Es ist nun möglich das redirect_to_https Attribut für Webspace- und Redirect-Subdomains zu manipulieren.

2020-09-08

Es ist nun möglich Datenbanken anzulegen und zu löschen.

2020-09-02

Es ist nun möglich sich Datenbanken anzeigen zu lassen.

2020-09-01

Es ist nun möglich sich Pakete anzeigen zu lassen.

2020-08-20

Es ist nun möglich Subdomains in Webspace bzw. Redirect umzuwandeln indem man den Webspace-Pfad bzw. die Ziel-URL PATCHt.

2020-07-14

• Es ist nun möglich Kundendaten abzurufen.
• Es ist ebenfalls möglich die Domainliste nach Kundennummern zu filtern.

2020-07-02

Es ist nun möglich, Web-Redirect-Subdomains anzulegen.

2020-06-16

Es ist nun möglich, Email-Subdomains anzulegen.

2020-06-11

Application Passwords für Email-Postfächer können nun angelegt und gelöscht werden.

2020-06-10

• Die Standard-PHP-Version für Webhosting-Subdomains kann nun gesetzt werden.
• Der Webspace-Pfad von Webhosting-Subdomains kann nun gesetzt werden.

2020-05-19

Der DNS-Migrationsmodus kann nun für Domains gesetzt werden.

2020-03-06

Es ist nun möglich, Autorespondern von E-Mail-Postfächern ein Ablaufdatum zuzuordnen.

2019-10-25

Es ist nun möglich E-Mail-Adressen serverseitig nach Adressen zu filtern.

2019-08-14

Beschreibungen (description) von E-Mailadressen können nun mittels PATCH geändert werden.

2019-08-13

Beim Anlegen von E-Mailadressen ist es nun möglich den Spamschutz zu konfigurieren. Wir raten jedoch dazu, den Standardwert reject nicht zu ändern.

2019-08-12

• Autoresponder können nun gesetzt, aktiviert und deaktiviert werden.
• Statt neue Postfachpasswörter von Hand zu setzen, ist es nun auch möglich mittels eines POSTs ein neues, sicheres Passwort zu setzen

2019-08-09

E-Mail-Adressen mit +-Zeichen können nun als Weiterleitungsziele (forward_to) für Postfächer und Weiterleitungen verwendet werden.

2019-08-08

Postfachpasswörter können nun geändert werden.

2019-06-11

Es ist nun möglich, bei E-Mail-Adressen zusätzliche Empfänger hinzuzufügen und zu löschen.

2019-05-17

E-Mail-Adressen können nun gelöscht werden.

2019-03-06 → Ende der Betaperiode

Die meisten Änderungen ergeben sich aus der Tatsache, dass einige Entscheidungen dem JSON:API-Standard widersprachen. Insbesondere müssen Untertypen die bisher per /data/type gesetzt wurden, nun unterhalb der attributes gesetzt werden und der Name darf nicht type sein.

• /dns-records:
  • Beim Abruf heisst /data/attributes/type nun /data/attributes/record_type.
  • Beim Anlegen muss das type-Feld nun immer dns-record lauten. Der Untertyp wird mittels /data/attributes/record_type definiert.
• /domain-availability: Die Ergebnisse sind nun ebenfalls nach JSON:API-Art gewrapt.
• /email-addresses:
  • Beim Abruf heisst /data/attributes/type nun /data/attributes/address_type.
  • Beim Anlegen muss das type-Feld nun immer email-address lauten. Der Untertyp wird mittels /data/attributes/address_type definiert.
• /queue-jobs: /data/attributes/type heisst nun /data/attributes/job_type.
• /subdomains:
  • Beim Abruf heisst /data/attributes/type nun /data/attributes/subdomain_type.
  • Beim Anlegen muss das type-Feld nun immer subdomain lauten. Der Untertyp wird mittels /data/attributes/subdomain_type definiert.

2019-02-26

• /domain-availability: Domains können nun auf Verfügbarkeit geprüft werden.
• /subdomains: Beim Anlegen von Webhosting-Subdomains kann nun optional die PHP-Version angegeben werden.

Allgemeine Prinzipien

Basis-URL

Sämtliche URLs sind relativ zum Hostnamen https://api.variomedia.de/.

Authentifizierung

Authentifizierung findet mittels des Authorization:-Headers statt.

Um das Testen in Browsern zu ermöglichen, ist es möglich traditionelle HTTP Basic Authentication zu verwenden. Hierbei nutzen Sie token als User und den Token selbst als Passwort.

Alternativ kann auch die Methode token benutzt werden:

Authorization: token ihr-token

Tokens deren Kontakte gelöscht werden, werden automatisch ungültig.

Content-Type

Vorzugsweise sollten Sie Ihre Request mit dem Content-Type application/vnd.api+json verschicken. Die API verlangt das jedoch nicht und sollte es nicht gesetzt sein, sind die Server-Antworten als application/json angegeben, um das Testen im Browser zu erleichtern.

Bei allen Requests, die eine JSON-Payload im Body haben, muss der Content-Type auf entweder application/vnd.api+json oder application/json gesetzt werden.

Versionierung

Versionierung findet per Accept:-Header statt. Die aktuelle Version lautet:

Accept: application/vnd.variomedia.v1+json

Wird keine Version angegeben, erhalten Sie automatisch die neuste Version.

Wir empfehlen daher immer explizit eine API-Version zu setzen.

Rückwärtskompatible Änderungen wie das Hinzufügen von Attributen in Responses veranlassen keine Änderung der API-Version.

Limits

Derzeit besteht eine Durchsatzbegrenzung (Rate-Limit) von 10 Request / 10 Sekunden per IP. Sollte sie überschritten werden, liefert die API Statuscode 429 zurück.

Sollten Sie zu viele Fehler verursachen, wird der Zugang zur API vorrübergehend gesperrt.

Objekt-Filter

Standardmäßig erhalten Sie beim Auflisten von Objekten (in der Regel GET-Request gegen die Basis-URL des Objektes) alle für den aktuellen Kunden oder Reseller relevanten Objekte zurück.

Dies kann insbesondere bei Resellern jedoch schnell unübersichtlich werden. Deshalb erlauben die meisten Endpunkte eine Filterung anhand von bestimmten Attributen. Welche das sind, wird in der jeweiligen Objektdokumentation aufgelistet.

Filter werden per URL-Parameter übergeben und haben stets die gleiche Form: filter[ATTRIBUT]=WERT.

Wünschen Sie also eine Liste aller API-Objekte vom Typen OBJEKT, die ein Attribut ATTRIBUT mit dem Wert WERT haben, würden Sie die folgende URL verwenden:

https://api.variomedia.de/OBJEKT?filter[ATTRIBUT]=WERT

Sie können mehrere WERTe für ATTRIBUT angeben indem sie entweder mehrere URL-Parameter übergeben (die Standardgemäß mit &-Zeichen getrennt werden):

?filter[ATTRIBUT]=WERT_1&filter[ATTRIBUT]=WERT_2

Oder indem Sie die Werte mit Kommas trennen:

?filter[ATTRIBUT]=WERT_1,WERT_2

In beiden Fällen wird der Filter als ein logisches Oder interpretiert. ATTRIBUT darf also sowohl WERT_1, als auch WERT_2 sein.

Falls Sie Filter für mehrere unterschiedliche Attribute anwenden, werden die Filter als logisches Und angewendet.

Zum Beispiel:

?filter[domain]=domain1.de,domain2.de&filter[package_id]=1,2

Liefert eine Liste für die Domains domain1.de und domain2.de, aber nur falls sie in den Paketen 1 oder 2 liegen.

Job Queue

Bei Schreiboperationen, kann es vorkommen, dass bestimmte Aktionen asynchron erfolgen und mehrere Minuten brauchen, bis sie erledigt sind.

In dem Fall erhalten Sie vom Server ein 202 Accepted zurück zusammen mit einem Link zu einem Job der den Status pending hat.

Den Link finden Sie entweder im Content-Location-Header oder im JSON-Body unter data.links.queue-job.

Sobald ein Job erfolgreich abgearbeitet ist, wird sein Status auf done gesetzt.

GET /queue-jobs

Gibt Ihnen eine Liste von Jobs die im Status pending sind. Es gibt derzeit keine Filter.

Anhand von /data/links/object lässt es sich auf das Objekt schließen, das erstellt/bearbeitet wird und anhand von /data/relationsships/owner/data/id können Reseller die Jobs ihren Endkunden zuordnen.

Bitte beachten:

• Erledigte Jobs werden nach 24h gelöscht.
• Im Kundenmenü ausgelöste Jobs erscheinen hier nicht.

GET /queue-jobs/{id}

Liefert einen einzelnen Job anhand seiner ID zurück.

Kunden

GET /customers

Liefert die Liste aller Ihrer Kunden. Als Kontaktinformationen werden die Daten des Hauptkontakts des jeweiligen Kundenkontos angezeigt. Es gibt derzeit keine Filter.

GET /customers/{id}

Liefert Details für Kunden {id}.

Manipulation

PATCH /customers/{id}

Kundenmenüzugang

Folgender Body für PATCH /customers/2042 sperrt den Zugang zum Kundenmenü für den Kunden mit der Kundennummer 2042:

{
  "data": {
    "type": "customer",
    "id": "2042",
    "attributes": {
      "is_login_disabled": true
    }
  }
}

Das Entsperren funktioniert analog, indem man false setzt.

Externe Kundennummern

Reseller können Ihren Kunden einzigartige externe Kundennummern zuweisen die aus ASCII-Zeichen, Zahlen, ., - und _ bestehen. Diese Nummern können für die Identifikation Ihrer Kunden in unserem System verwendet werden:

{
  "data": {
    "type": "customer",
    "id": "2042",
    "attributes": {
      "external_customer_id": "abc-123"
    }
  }
}

Eine externe Kundennummer kann entfernt werden, indem sie auf null gesetzt wird.

Domains

Domains können:

1. über Variomedia registriert,
2. einer Präsenz zugeordnet (d.h. sie wird bei Variomedia genutzt, aber woanders registriert; auch „externe Domain“ genannt),
3. beides sein.

Deshalb enthält die Reponse zwei Unterfelder: registration und presence. Je nach Domaintyp, kann eines der beiden Felder null sein, was eine Unterscheidung ermöglicht.

GET /domains

Liefert eine Liste aller Domains mit Erstellungs- und Ablaufdatum.

Mögliche Filter:

• owner_id: Kundennummer
• package_id: Paket

GET /domains/{domain-name}

Liefert Details zur Domain {domain-name}.

Manipulation

PATCH /domains/{domain-name}

Ermöglicht die Manipulation von existierenden Domains. Bitte beachten Sie, dass die Domain in der URL und das id-Feld im Body identisch sein müssen.

DNS-Updateschutz

Den Updateschutz für DNS-Einträge aktiveren, beziehungsweise deaktivieren:

{
    "data": {
        "id": "beispielkunde.info",
        "type": "domain",
        "attributes": {
            "presence": {
                "dns_update_lock": false
            }
        }
    }
}

DNS-Migrationsmodus

Analog können Sie ebenfalls den DNS-Migrationsmodus beeinflussen:

{
    "data": {
        "id": "beispielkunde.info",
        "type": "domain",
        "attributes": {
            "presence": {
                "dns_migration_mode": {
                    "enabled": true
                }
            }
        }
    }
}

Pakete

Pakete (manchmal auch Präsenzen genannt) verbinden Kunden, Domains und Hostingdienstleistungen wie Webhosting oder E-Mail-Adressen. Jedes Paket enthält Links zu allen dem Paket zugeordneten Objekten im relationships-Teil der Antwort.

GET /packages

Liefert eine Liste von angelegten Paketen.

Mögliche Filter:

• owner_id: Kundennummer
• plan_id: Tarif-ID

GET /packages/{id}

Liefert Details zum Paket {id}.

Derzeit ist nur lesender Zugriff möglich.

Tarife

Tarife definieren die Leistungen, die für ein Paket freigeschaltet sind.

GET /plans

Liefert eine Liste von angelegten Tarife.

GET /plans/{id}

Liefert Details zum Tarif {id}.

Derzeit ist nur lesender Zugriff möglich.

DNS-Einträge

GET /dns-records

Liefert eine Liste aller DNS-Einträge.

Mögliche Filter:

• domain: Domainname (ohne Subdomains)
• package_id: Paket

GET /dns-records/{id}

Liefert Details zum DNS-Eintrag {id}.

Erstellen

POST /dns-records

Erstellt einen neuen DNS-Eintrag anhand des POST-Bodys.

Derzeit können folgende Typen von DNS-Einträgen erstellt werden:

• A
• AAAA
• ALIAS (Ähnlich CNAME, jedoch ohne Subdomain-Zwang.)
• CAA
• CNAME
• MX
• SRV
• TXT

Zum Beispiel:

{
  "data": {
    "type": "dns-record",
    "attributes": {
      "record_type": "A",
      "name": "local",
      "domain": "domain.de",
      "data": "127.0.0.1",
      "ttl": 800
    }
  }
}

legt einen A-Eintrag für die Domain local.domain.de mit der Adresse 127.0.0.1 an.

• Das Feld domain muss eine Präsenz-Domain sein.
• Das ttl (Time To Live) Feld ist in Sekunden (300–86400) und optional. Beim Fehlen wird der gleiche Systemdefault benutzt, wie im Kundenmenü.

Besonderheiten:

• CNAME-Einträge werden im Gegensatz zum Kundenmenü immer absolut interpretiert. Die data-Felder foo.com und foo.com. werden also identisch behandelt.

Löschen

DELETE /dns-records/{id}

Löscht einen DNS-Eintrag mit der id {id}.

Bitte beachten Sie:

• Gelöschte DNS-Einträge können nicht ohne weiteres wiederhergestellt werden!

• Manche DNS-Einträge können nicht gelöscht werden. Zum Beispiel die von uns verwalteten DKIM-Einträge.

• Falls Sie die DNS-Einträge, die das base-Tag im Kundenmenü tragen ändern möchten, sollten Sie unbedingt den Update-Schutz aktivieren, damit Vorgänge wie Tarifwechsel sie nicht zurücksetzen.

  Sie können dies entweder von Hand im Kundenmenü oder mit Hilfe des Domain-Endpunktes dieser API erledigen.

Subdomains

Es gibt drei Typen von Subdomains:

1. webspace: Volles Webhosting und E-Mail.
2. redirect: HTTP-Redirect und E-Mail.
3. email: Subdomain die ausschließlich für E-Mail genutzt wird.

GET /subdomains

Liefert eine Liste von Subdomains für den aktuellen Kunden.

Mögliche Filter:

• package_id: Pakete
• domain: Domains als Strings; z.B. variomedia.de

GET /subdomains/{id}

Liefert Details zur Subdomain mit der ID {id}.

Erstellen

POST /subdomains

Erstellt eine neue Subdomain anhand des POST-Bodys.

Webspace

Ein Beispiel für einen POST-Body, der eine Webspace-Subdomain „sub“ für die Domain „domain.de“ anlegt, die auf den Pfad „/sub-webspace/“ zeigt:

{
  "data": {
    "type": "subdomain",
    "attributes": {
      "subdomain_type": "webspace",
      "description": "Eine freiwillige Beschreibung.",
      "domain": "domain.de",
      "subdomain": "sub",
      "webspace": {
        "path": "/sub-webspace/"
      }
    }
  }
}

Optional kann zusätzlich eine php_version als String übergeben werden, die standardmäßig für PHP-Skripte verwendet wird. Beim Weggelassen wird automatisch die empfohlene PHP-Version verwendet.

Derzeit sind folgende Versionen zulässig:

• "5.6" (keine Sicherheitsupdates mehr verfügbar!)
• "7.1" (keine Sicherheitsupdates mehr verfügbar!)
• "7.2" (keine Sicherheitsupdates mehr verfügbar!)
• "7.3" (keine Sicherheitsupdates mehr verfügbar!)
• "7.4" (keine Sicherheitsupdates mehr verfügbar!)
• "8.0" (keine Sicherheitsupdates mehr verfügbar!)
• "8.1" (unterstützt bis 25.11.2024)
• "8.2" (unterstützt bis 08.12.2025)
• "8.3" (unterstützt bis 23.11.2026)

Redirect

Ein Beispiel für einen POST-Body, der eine Redirect-Subdomain „sub“ für die Domain „domain.de“ anlegt, die Zugriffe nach „sub2.domain.de“ mittels eines Location-Headers weiterleitet und den Pfad dynamisch umschreibt:

{
  "data": {
    "type": "subdomain",
    "attributes": {
      "subdomain_type": "redirect",
      "description": "Eine freiwillige Beschreibung.",
      "domain": "domain.de",
      "subdomain": "sub",
      "redirect": {
        "dynamic": true,
        "target": "https://sub2.domain.de/"
      }
    }
  }
}

Ist dynamic auf false gesetzt, wird hart auf die target-URL umgeleitet. Wenn es true ist, wird der Pfad übernommen. Also z.B. https://sub.domain.de/foo/bar würde auf https://sub2.domain.de/foo/bar umleiten.

Für die target-URL gelten die gleichen Regeln, wie im Kundenmenü.

Email

Ein Beispiel für einen POST-Body, der eine Email-Subdomain „sub“ für die Domain „domain.de“ anlegt:

{
  "data": {
    "type": "subdomain",
    "attributes": {
      "subdomain_type": "email",
      "description": "Eine freiwillige Beschreibung.",
      "domain": "domain.de",
      "subdomain": "sub"
    }
  }
}

Manipulation

PATCH /subdomains/{id}

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

PHP-Version

Für Webspace-Subdomains können Sie die Standard-PHP-Version setzen:

{
  "data": {
    "type": "subdomain",
    "id": "42",
    "attributes": {
      "webspace": {
        "php_version": "7.4"
      }
    }
  }
}

Für gültige Versionen, vergleichen Sie bitte die Liste von oben. Bei null wird die Standardversion des Pakets, in dem sich die Subdomain befindet, verwendet.

Pfad zu Webspace

Um den Webspace-Pfad zu setzen:

{
  "data": {
    "type": "subdomain",
    "id": "42",
    "attributes": {
      "webspace":{
        "path": "/ihr/wordpress/"
      }
    }
  }
}

Wenn Sie den Webspace-Pfad für eine Redirect- oder eine Email-Subdomain PATCHen, wird sie automatisch in eine Webspace-Subdomain umgewandelt.

Redirect-Ziel

Um die Ziel-URL einer Redirect-Subdomain zu ändern:

{
  "data": {
    "type": "subdomain",
    "id": "42",
    "attributes": {
      "redirect": {
        "target": "https://beispielkunde.info/"
      }
    }
  }
}

Sollte die Subdomain bisher uninitialisiert sein (d.h in der Liste erscheint sie als Weiterleitung, jedoch ohne Weiterleitungsdaten), wird im gleichen Schritt die Weiterleitung as statisch eingerichtet.

Wenn Sie die Ziel-URL für eine Webspace- oder eine Email-Subdomain PATCHen, wird sie automatisch in eine statische Redirect-Subdomain umgewandelt.

Dynamische Redirects

Sie können eine Redirect-Subdomain dynamisch machen (oder nicht). Bitte beachten Sie, dass um eine Redirect-Subdomain dynamisch zu machen, die Ziel-URL mit einem / enden muss.

{
  "data": {
    "type": "subdomain",
    "id": "42",
    "attributes": {
      "redirect": {
        "dynamic": true
      }
    }
  }
}

Es ist nicht möglich dies für uninitialisierte Subdomains anzuwenden.

Automatische Weiterleitung zu HTTPS

Um das redirect_to_https-Attribut zu manipulieren, benutzen Sie

{
  "data": {
    "type": "subdomain",
    "id": "42",
    "attributes": {
      "redirect": {
        "redirect_to_https": true
      }
    }
  }
}

für Redirect-Subdomains bzw.

{
  "data": {
    "type": "subdomain",
    "id": "42",
    "attributes": {
      "webspace": {
        "redirect_to_https": true
      }
    }
  }
}

für Webhosting-Subdomains.

Es ist nicht möglich dies für uninitialisierte Redirect-Subdomains anzuwenden.

Datenbanken

Derzeit unterstützen wir zwei Arten von Datenbanken: MySQL und MariaDB in verschiedenen Versionen.

GET /databases

Liefert eine Liste von Datenbanken für den aktuellen Kunden.

Mögliche Filter:

• package_id: Pakete
• server: Der Datenbankserver auf dem die Datenbank liegt (z.B. db22).
• db_type: Der Datenbanktyp. Derzeit mysql oder mariadb.
• version: Die Version der Datenbank (z.B. 8.0).

GET /databases/{id}

Liefert Details zur Datenbank mit der ID {id}.

Anlegen

Datenbanken werden stets auf dem aktuellen Standardserver für die jeweilige Datenbankversion angelegt. Es ist nicht möglich die API zum Anlegen von Datenbanken auf Datenbankservern zu nutzen, die auf einem dedizierten Server laufen.

POST /databases

Derzeit können folgende Kombinationen von Datenbank und Version angelegt werden. Es werden die gleichen Datenbanken und Versionen wie im Kundenmenü unterstützt.

Jede Datenbank ist einem Paket zugeordnet.

Um einen MariaDB 10.5 Datenbank im Paket mit der ID 42 und der Beschreibung "Eine freiwillige Beschreibung." anzulegen, benutzen Sie folgenden POST-Body:

{
  "data": {
    "type": "database",
    "attributes": {
      "package_id": "42",
      "db_type": "mariadb",
      "version": "10.11",
      "description": "Eine freiwillige Beschreibung."
    }
  }
}

Ein sicheres Passwort wird für Sie automatisch erstellt und mit der Bestätigung – zusammen mit dem Server, auf dem die Datenbank angelegt wurde und der Datenbank-ID – zurückgegeben.

Löschen

DELETE /databases/{id}

Löscht die Datenbank mit der ID {id}.

E-Mail-Adressen

Es gibt zwei Sorten von E-Mail-Adressen:

1. 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.
2. 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.

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

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.

Verfügbarkeit von Domains

Mittels

GET /domain-availability/domain1.de,domain2.de,...

können Sie überprüfen, ob eine Domain zur Registrierung zur Verfügung steht.

Falls available den Wert null hat, bedeutet es, dass ein Fehler aufgetreten ist.

Bitte beachten Sie, dass die Geschwindigkeit und Zuverlässigkeit dieses Endpunktes von den eigentlichen Domain-Registries abhängt. Unterschiedliche TLDs dauern unterschiedlich lange und manche Registries neigen zu Ausfällen.

Limits

Derzeit können maximal 10 Domains gleichzeitig überprüft werden.