Absenderidentitäten

E-Mails werden mit einer Absenderidentität des Kontos versendet: einer eigenen Domain oder einer Adresse. Oblic sendet nur mit verifizierten Identitäten. Zum Hinzufügen und Löschen ist ein Schlüssel mit identities:manage erforderlich; zum Auflisten identities:manage oder email:send.


POST/external/v1/identities

Eine Identität hinzufügen

  • Name
    identityType
    Typ
    string
    Beschreibung

    Erforderlich: Domain oder Email, genau in dieser Schreibweise.

  • Name
    identity
    Typ
    string
    Beschreibung

    Erforderlich: die Domain, etwa example.com, oder die Adresse, etwa orders@example.com, mit höchstens 255 Zeichen.

  • Name
    email
    Typ
    string
    Beschreibung

    Bei Domain erforderlich: eine Adresse dieser Domain, mit der die Identität sendet.

  • Name
    displayName
    Typ
    string
    Beschreibung

    Erforderlich: der Absendername mit höchstens 255 Zeichen, ohne <, >, " oder Zeilenumbruch.

  • Name
    replyTo
    Typ
    string
    Beschreibung

    Die Adresse, an die Antworten gehen.

Eine Domain hinzufügen

curl -X POST https://api.oblic.app/external/v1/identities \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "identityType": "Domain",
    "identity": "example.com",
    "email": "orders@example.com",
    "displayName": "Example Store"
  }'

Die Antwort enthält die Identität. Bei einer Domain enthält payload die zu veröffentlichenden DNS-Einträge, jeweils einen CNAME von key zu value: die drei DKIM-Einträge des E-Mail-Anbieters, danach den Eintrag von Oblic.

Auszug aus der Antwort

{
  "status": "success",
  "data": {
    "id": "OEM000R7ZM4Q2VXH00",
    "email": "orders@example.com",
    "displayName": "Example Store",
    "domain": "example.com",
    "verificationStatus": "PENDING",
    "sendingMode": "OWN",
    "payload": [
      { "key": "6gbrjpgwjskckoa6a5zn6fwqkn67xbtw._domainkey.example.com", "value": "6gbrjpgwjskckoa6a5zn6fwqkn67xbtw.dkim.amazonses.com" },
      { "key": "pwmp4w2fqavhvhqfsxe3ch7mhc6y3kzj._domainkey.example.com", "value": "pwmp4w2fqavhvhqfsxe3ch7mhc6y3kzj.dkim.amazonses.com" },
      { "key": "y2xbgbc34rt5t5yjzu4mktqq3e4zrl7n._domainkey.example.com", "value": "y2xbgbc34rt5t5yjzu4mktqq3e4zrl7n.dkim.amazonses.com" },
      { "key": "_9f86d081884c4d659a2feaa0c55ad015.example.com", "value": "2c26b46b68ffc68ff99b453c1d304134.qwertyui.validation.oblic.app" }
    ]
  },
  "errors": null
}

Das Hinzufügen einer bereits im Konto vorhandenen Identität gibt deren aktuellen Zustand zurück. Felder ohne Wert werden ausgelassen.


Die Identität verifizieren

  • Eine Domain wird verifiziert, sobald ihre DNS-Einträge veröffentlicht sind: Mit den DKIM-Einträgen signiert der Anbieter die E-Mails; Oblics eigener Eintrag weist die Zugehörigkeit der Domain zum Konto nach. Jede Adresse einer verifizierten Domain kann senden.
  • Eine Adresse erhält vom E-Mail-Anbieter einen Link, den ihr Inhaber öffnet. Sie kann senden, sobald auch ihre Domain als Domainidentität des Kontos verifiziert ist.
  • Eine Adresse bei einem öffentlichen Maildienst, etwa Gmail oder Outlook, kann keine Einträge veröffentlichen. Über einen anderen Anbieter versendete Nachrichten bestehen dessen Prüfungen nicht. Oblic versendet sie daher über seinen eigenen Dienst mit sendingMode gleich OBLIC: von Oblics Versanddomain unter „Ihr Name via Oblic“, mit Antworten an die ursprüngliche Adresse. Oblic sendet einen 72 Stunden gültigen Link zur Bestätigung der Inhaberschaft an die Adresse; vor dessen Öffnung kann die Identität nicht senden. Die Domain eines öffentlichen Maildienstes kann nicht als Domain hinzugefügt werden. Dieser Modus erfordert eine konfigurierte Versanddomain von Oblic; andernfalls wird die Adresse mit PUBLIC_MAILBOX_DOMAIN abgelehnt.
  • Oblics eigene Domains können keinem Konto als Identität gehören.

verificationStatus ist SUCCESS, sobald eine Identität senden kann, und bis dahin PENDING.

AbgelehntcdWann
400INVALID_IDENTITYEine Email-Identität ist keine E-Mail-Adresse, oder die email einer Domain gehört nicht zu dieser Domain
400PUBLIC_MAILBOX_DOMAINDie Domain eines öffentlichen Maildienstes, etwa gmail.com, als Domain, oder eine öffentliche Email-Identität ohne konfigurierte Oblic-Versanddomain
400OBLIC_DOMAINEine von Oblics eigenen Domains
400IDENTITY_LIMIT_REACHEDDer E-Mail-Anbieter hat seine zulässige Anzahl an Identitäten erreicht
503EMAIL_PROVIDER_UNAVAILABLEDer E-Mail-Anbieter ist nicht erreichbar; versuchen Sie es erneut

GET/external/v1/identities

Identitäten auflisten

Die Identitäten des Kontos, die vor dem Aufruf verifizierten zuerst. Beim Auflisten werden auch ausstehende Identitäten erneut geprüft. Eine Identität, die diese Prüfung verifiziert, wird in derselben Antwort als SUCCESS aufgeführt.


DELETE/external/v1/identities/{identityId}

Eine Identität löschen

Die Identität kann nicht mehr senden. Bei einer über Oblic versendeten Adresse endet auch ihre Bestätigung: Nach erneutem Hinzufügen muss sie erneut bestätigt werden. Die Antwort ist 200, unabhängig davon, ob das Konto die Identität hatte.

War diese Seite hilfreich?