API-Schlüssel

API-Schlüssel authentifizieren Ihre Anfragen an die REST-API, Ihre SMTP-Verbindungen und Sitzungen mit API-Schlüssel auf dem MCP-Server. Diese Seite erklärt die beiden Scopes, wie Sie Schlüssel erstellen und verwalten und wie Sie sie sicher speichern und rotieren.

So funktionieren API-Schlüssel

• Jeder Schlüssel gehört zu genau einem Workspace. Alles, was Sie damit tun, geschieht in diesem Workspace.
• Neue Schlüssel beginnen mit secret_, gefolgt von 32 Buchstaben und Ziffern, zum Beispiel secret_••••••••. Schlüssel, die vor der Einführung des Präfixes erstellt wurden, funktionieren weiterhin.
• Emailit zeigt den vollständigen Schlüssel nur einmal an, wenn Sie ihn erstellen oder neu generieren. Kopieren Sie ihn dann; später können Sie ihn nicht mehr ansehen.
• Sie senden den Schlüssel als Bearer-Token: Authorization: Bearer secret_…. Bei SMTP ist der Schlüssel das Passwort.

Scopes

Jeder Schlüssel hat einen von zwei Scopes. Sie wählen den Scope beim Erstellen des Schlüssels.

Ein reiner Sende-Schlüssel, der einen anderen Endpunkt aufruft, erhält 403 mit einer Meldung wie Permission denied: read. Verwenden Sie Schlüssel mit Vollzugriff für Backoffice-Jobs, die Ressourcen verwalten, und reine Sende-Schlüssel für alles, was nur senden muss.

Schlüssel auf eine Domain beschränken

Wenn Sie einen reinen Sende-Schlüssel erstellen, können Sie eine verifizierte Versanddomain auswählen. Der Schlüssel kann dann nur von Adressen dieser Domain senden:

• Per API gibt das Senden von einer anderen Domain 403 mit "error": "Domain not authorized" zurück.
• Per SMTP wird die Nachricht nach DATA mit 530 API key is restricted to sending domain: … abgelehnt.

Beschränkte Schlüssel eignen sich gut als Zugangsdaten pro App oder pro Kunde und für Schlüssel, die Sie an Drittsoftware wie ein CMS-Plugin weitergeben müssen.

Voraussetzungen

• Um Schlüssel zu erstellen, zu bearbeiten, neu zu generieren oder zu löschen, benötigen Sie im Workspace die Rolle Admin. Mitglieder mit der Rolle Member sehen die Liste der Schlüssel, können sie aber nicht ändern. Siehe Mitglieder und Rollen.
• Um mit einem Schlüssel zu senden, benötigen Sie mindestens eine verifizierte Versanddomain.

API-Schlüssel erstellen

curl https://api.emailit.com/v2/api-keys \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-web",
    "scope": "sending",
    "sending_domain_id": "dom_3xQ7mLp2RkT9vB4nHs8YcWd1Ze6"
  }'

{
  "object": "api_key",
  "id": "key_4F2kN8sQwE1rT6yU3iO9pA7sD5f",
  "name": "production-web",
  "scope": "sending",
  "sending_domain_id": "dom_3xQ7mLp2RkT9vB4nHs8YcWd1Ze6",
  "last_used_at": null,
  "created_at": "2026-10-01T09:30:00.000Z",
  "updated_at": "2026-10-01T09:30:00.000Z",
  "key": "secret_••••••••••••••••••••••••••••••••"
}

Schlüssel verwenden

Übergeben Sie den Schlüssel im Header Authorization jeder API-Anfrage:

curl https://api.emailit.com/v2/emails \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <hello@acme.com>",
    "to": "ada@example.com",
    "subject": "Your order has shipped",
    "text": "Your order #1042 is on its way."
  }'

Um per SMTP zu senden, verwenden Sie den Schlüssel als Passwort:

Alle Optionen finden Sie unter SMTP-Einstellungen.

Schlüssel verwalten

Öffnen Sie einen Schlüssel unter Email API›API Keys, um Scope, Domain, das Datum unter Created, den Zeitpunkt unter Last used und die passenden SMTP-Einstellungen zu sehen.

Last used wird aktualisiert, sobald der Schlüssel eine API-Anfrage oder eine SMTP-Anmeldung authentifiziert. Ein Schlüssel, der nie verwendet wurde, zeigt Never. In der API akzeptieren Endpunkte, die eine Schlüssel-ID erwarten, auch den Namen des Schlüssels.

Schlüssel sicher speichern

• Schlüssel auf dem Server behalten. Legen Sie einen Schlüssel nie in Browser-JavaScript, eine mobile App, ein öffentliches Repository oder ein Support-Ticket. Wer den Schlüssel kennt, kann in Ihrem Namen E-Mails senden und Ihre Credits verbrauchen.
• Umgebungsvariablen oder einen Secrets-Manager verwenden. Laden Sie den Schlüssel zur Laufzeit, zum Beispiel aus EMAILIT_API_KEY. Nehmen Sie .env-Dateien in .gitignore auf.
• Jeder App und Umgebung einen eigenen Schlüssel geben. Mit getrennten Schlüsseln für Produktion, Staging und jedes Drittanbieter-Tool sehen Sie leicht, wer was gesendet hat, und können einen Schlüssel widerrufen, ohne die anderen anzutasten.
• Den engsten Scope verwenden. Wenn eine App nur E-Mails sendet, geben Sie ihr einen reinen Sende-Schlüssel, nach Möglichkeit auf ihre Domain beschränkt.
• Nutzung beobachten. Email API›Logs listet API- und SMTP-Anfragen pro Schlüssel auf, und Sie können Email API›Emails nach API-Schlüssel filtern. Siehe Anfrage-Logs.
• Bei einem Leak schnell handeln. Wenn ein Schlüssel offengelegt wurde, generieren Sie ihn sofort neu oder löschen Sie ihn und prüfen Sie dann die Logs auf unerwartete Versände.

Schlüssel ohne Ausfallzeit rotieren

Beim Neugenerieren wird das alte Secret sofort ungültig; nutzen Sie das deshalb nur, wenn ein Schlüssel kompromittiert ist. Für eine geplante Rotation betreiben Sie alten und neuen Schlüssel parallel:

1. Neuen Schlüssel erstellen. Legen Sie einen Schlüssel mit demselben Scope und derselben Domain-Beschränkung an wie der Schlüssel, den Sie ersetzen. Geben Sie ihm einen Namen mit Datum, etwa production-web-2026-10.

2. Neuen Schlüssel bereitstellen. Aktualisieren Sie das Secret in Ihrem Secrets-Manager oder Ihrer Umgebung und rollen Sie es auf alle Server, Worker und geplanten Jobs aus, die den alten Schlüssel verwenden.

3. Umstellung bestätigen. Öffnen Sie den neuen Schlüssel und prüfen Sie, ob Last used aktuell ist. Filtern Sie unter Email API›Logs nach dem alten Schlüssel und prüfen Sie, ob keine Anfragen mehr eingehen.

4. Alten Schlüssel löschen. Wenn sich der Zeitpunkt unter Last used beim alten Schlüssel nicht mehr ändert, löschen Sie ihn.

Fehlerbehebung

Siehe auch