Authentifizierung

Jede Anfrage an die Emailit-API muss im Header Authorization Zugangsdaten mitsenden. Diese Seite beschreibt die beiden Arten von Zugangsdaten (API-Schlüssel und OAuth-Zugriffstoken), was jeder Scope erlaubt, und alle Authentifizierungsfehler, die Sie zurückbekommen können.

API-Schlüssel

Ein API-Schlüssel gehört zu einem Workspace, und jede Anfrage mit diesem Schlüssel wirkt auf diesen Workspace. Schlüssel sehen so aus:

secret_Xq7pL2mN9vB4kR8tW1yZ6cH3jF5dS0aG

Also secret_, gefolgt von 32 Buchstaben und Ziffern. Schlüssel, die vor dem Format secret_ erstellt wurden, haben kein Präfix und funktionieren weiterhin.

Erstellen Sie Schlüssel in der Weboberfläche unter Email API›API Keys oder mit API-Schlüssel erstellen. Das Secret wird nur einmal angezeigt, wenn Sie den Schlüssel erstellen oder neu generieren. Speichern Sie es daher sofort. Wie Sie Schlüssel verwalten, erfahren Sie unter API-Schlüssel.

Dieselben Schlüssel dienen als SMTP-Passwort für das SMTP-Relay.

Schlüssel mit jeder Anfrage senden

Verwenden Sie das Schema Bearer im Header Authorization. Die API akzeptiert keine Schlüssel im Query-String oder im Anfrage-Body.

curl https://api.emailit.com/v2/domains \
  -H "Authorization: Bearer $EMAILIT_API_KEY"

const response = await fetch('https://api.emailit.com/v2/domains', {
  headers: { Authorization: `Bearer ${process.env.EMAILIT_API_KEY}` },
});
const domains = await response.json();

import os
import requests

response = requests.get(
    "https://api.emailit.com/v2/domains",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
)
domains = response.json()

Die SDKs setzen diesen Header für Sie, wenn Sie dem Client den Schlüssel übergeben.

Scopes

Jeder Schlüssel hat einen von zwei Scopes. Sie wählen ihn beim Erstellen des Schlüssels und können ihn später nicht ändern.

Ein Schlüssel mit dem Scope sending kann diese Endpunkte aufrufen und sonst nichts:

Zum Lesen von E-Mails (auflisten, abrufen, Roh-MIME, Body, Metadaten, Anhänge und Status) ist ein Schlüssel mit dem Scope full nötig. Ruft ein Schlüssel mit dem Scope sending einen anderen Endpunkt auf, gibt die API 403 mit Permission denied: full zurück (oder Permission denied: read bei den Lese-Endpunkten für E-Mails).

Alle Endpunkte führt den Scope jedes Endpunkts auf.

Schlüssel auf eine Domain beschränken

Ein Schlüssel mit dem Scope sending lässt sich zusätzlich auf eine Versanddomain festlegen. Übergeben Sie die ID der Domain als sending_domain_id, wenn Sie den Schlüssel erstellen. Ein beschränkter Schlüssel kann nur von Adressen dieser Domain senden. Jede andere Domain in from gibt 403 zurück:

{
  "error": "Domain not authorized",
  "message": "API key is not authorized to send from this domain"
}

Domain-Beschränkungen gelten nur für Schlüssel mit dem Scope sending. Ein Schlüssel mit dem Scope full hat immer Zugriff auf alle Domains im Workspace.

OAuth-Zugriffstoken

Apps, die im Namen eines Emailit-Nutzers handeln, etwa MCP-Clients und Integrationen von Drittanbietern, fragen nicht nach einem API-Schlüssel. Sie verwenden stattdessen OAuth 2.1: Der Nutzer meldet sich bei Emailit an, wählt die Workspaces, die die App nutzen darf (alle oder nur ausgewählte), und bestätigt den Scope sending oder full. Danach erhält die App ein Zugriffstoken. Der Nutzer kann diesen Zugriff unter Verbundene Apps ändern oder widerrufen.

Senden Sie Zugriffstoken im selben Header wie API-Schlüssel:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…

Ein Zugriffstoken ist 15 Minuten gültig und wirkt auf den Standard-Workspace der Freigabe, mit dem gewährten Scope und der Rolle des Nutzers in diesem Workspace. Apps erneuern es mit dem Refresh-Token. Wie Sie eine solche App bauen, erfahren Sie unter OAuth-Apps.

Authentifizierungsfehler

Die Authentifizierung läuft vor allem anderen. Diese Fehler können deshalb von jedem Endpunkt zurückkommen.

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Invalid API key"
}

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Permission denied: full"
}

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Workspace is suspended"
}

{
  "code": "unverified_workspace_recipient",
  "error": "Workspace not verified",
  "message": "Unverified workspaces can only send to workspace members' account emails. Blocked recipient: ada@example.com.",
  "blocked_recipients": ["ada@example.com"]
}

Nicht verifizierte Workspaces

Neue Workspaces sind zunächst nicht verifiziert. Bis Emailit den Produktionszugang genehmigt, sendet die API nur an die E-Mail-Adressen der Konten der Workspace-Mitglieder. Senden, erneutes Senden oder Weiterleiten an andere Empfänger gibt 403 mit dem Code unverified_workspace_recipient und der Liste blocked_recipients zurück, und Kampagnen lassen sich überhaupt nicht senden. Für alles andere funktionieren Ihre API-Schlüssel normal.

Schlüssel geheim halten

Ein API-Schlüssel gewährt Zugriff auf Ihren Workspace. Behandeln Sie ihn deshalb wie ein Passwort.

• Rufen Sie die API nur von Ihrem Server auf. Legen Sie einen Schlüssel nie in Browser-JavaScript, einer mobilen App oder anderem Code ab, der auf dem Gerät einer anderen Person läuft.
• Halten Sie Schlüssel aus der Versionskontrolle heraus. Laden Sie sie aus Umgebungsvariablen oder einem Secrets-Manager.
• Erstellen Sie einen Schlüssel pro Anwendung und Umgebung und benennen Sie ihn nach dem Ort, an dem er verwendet wird. So können Sie einen Schlüssel widerrufen, ohne die anderen zu beeinträchtigen.
• Geben Sie jedem Schlüssel nur so viel Zugriff wie nötig: Für die meisten Anwendungen genügt ein Schlüssel mit dem Scope sending, beschränkt auf eine Domain.
• Prüfen Sie last_used_at unter API-Schlüssel auflisten und löschen Sie Schlüssel, die Sie nicht mehr verwenden.
• Wenn ein Schlüssel offengelegt wurde, generieren Sie ihn sofort neu oder löschen Sie ihn. Das alte Secret ist damit sofort ungültig.

Siehe auch