# API-Schlüssel

> Erstellen Sie API-Schlüssel mit Vollzugriff oder reine Sende-Schlüssel, beschränken Sie sie auf eine Domain, nutzen Sie sie für SMTP und rotieren Sie sie ohne Ausfallzeit.

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.

| | Full Access (`full`) | Sending Only (`sending`) |
| --- | --- | --- |
| E-Mail senden (`POST /emails`) | Ja | Ja |
| E-Mail verschieben, stornieren, erneut senden und weiterleiten | Ja | Ja |
| SMTP-Relay | Ja | Ja |
| E-Mails lesen (auflisten, abrufen, Rohquelle, Inhalt, Metadaten, Anhänge) | Ja | Nein |
| Domains, Vorlagen, Kontakte, Kontaktlisten, Sperrungen, Webhooks, Events, Kampagnen, Automatisierungen, Verifizierung und API-Schlüssel | Ja | Nein |
| MCP-Tools | Alle Tools | `send-email`, `update-email`, `cancel-email`, `retry-email`, `forward-email` und `get-current-workspace` |
| Auf eine Versanddomain beschränkbar | Nein | Ja |

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](/de/docs/workspaces/members-and-roles/).
- Um mit einem Schlüssel zu senden, benötigen Sie mindestens eine [verifizierte Versanddomain](/de/docs/domains/add-a-domain/).

## API-Schlüssel erstellen

**Weboberfläche**

  1. **API-Schlüssel öffnen.** Öffnen Sie **Email API → API Keys** und wählen Sie **Add API key**.

  2. **Schlüssel benennen.** Geben Sie unter **Name** einen Namen ein, der angibt, wo der Schlüssel verwendet wird, zum Beispiel `production-web` oder `wordpress-blog`. Namen müssen im Workspace eindeutig sein.

  3. **Scope wählen.** Wählen Sie unter **Scope** die Option **Full Access** oder **Sending Only**.

  4. **Optional die Domain beschränken.** Wählen Sie bei einem reinen Sende-Schlüssel unter **Domain** eine Versanddomain aus oder lassen Sie das Feld leer, um alle verifizierten Domains zu erlauben.

  5. **Schlüssel erstellen und kopieren.** Wählen Sie **Create**. Kopieren Sie den Schlüssel aus dem Dialog und speichern Sie ihn in Ihrem Secrets-Manager, bevor Sie den Dialog schließen. Emailit zeigt den Schlüssel nur einmal an.

**API**

  Rufen Sie [API-Schlüssel erstellen](/de/docs/api-reference/api-keys/create/) mit einem Schlüssel mit Vollzugriff auf. `scope` hat den Standardwert `full`; `sending_domain_id` gilt nur für reine Sende-Schlüssel.

```bash
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"
  }'
```

  Nur die Antwort mit `201` enthält `key`:

```json
{
  "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_••••••••••••••••••••••••••••••••"
}
```

  Ein bereits vergebener Name gibt `409` zurück.

## Schlüssel verwenden

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

```bash
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:

| Einstellung | Wert |
| --- | --- |
| Host | `smtp.emailit.com` |
| Port | `587` (STARTTLS, empfohlen), `465` (TLS), `2525` oder `2587` (STARTTLS) |
| Benutzername | `emailit` |
| Passwort | Ihr API-Schlüssel |

Alle Optionen finden Sie unter [SMTP-Einstellungen](/de/docs/smtp/settings/).

## 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.

| Aktion | Was passiert | API |
| --- | --- | --- |
| **Edit** | Benennt den Schlüssel um. Nur der Name wird gespeichert; um den Scope oder die Domain-Beschränkung zu ändern, erstellen Sie einen neuen Schlüssel und stellen auf ihn um. | [API-Schlüssel aktualisieren](/de/docs/api-reference/api-keys/update/) |
| **Regenerate** | Erzeugt ein neues Secret für denselben Schlüssel und zeigt es einmal an. Das alte Secret funktioniert sofort nicht mehr. Der Schlüssel behält ID, Name, Scope und Domain, und **Last used** wird zurückgesetzt. | [API-Schlüssel neu generieren](/de/docs/api-reference/api-keys/regenerate/) |
| **Delete** | Der Schlüssel funktioniert sofort nicht mehr und verschwindet aus der Liste. Das lässt sich nicht rückgängig machen. | [API-Schlüssel löschen](/de/docs/api-reference/api-keys/delete/) |

**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](/de/docs/logs/request-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

| Symptom | Ursache | Lösung |
| --- | --- | --- |
| `401` `Invalid API key` | Der Schlüssel wurde gelöscht, neu generiert oder falsch eingegeben. | Kopieren Sie den aktuellen Schlüssel in Ihre Konfiguration, einschließlich des Präfixes `secret_`. |
| `403` `Permission denied: read` oder `Permission denied: full` | Ein reiner Sende-Schlüssel hat einen Endpunkt außerhalb seines Scopes aufgerufen. | Verwenden Sie für diesen Aufruf einen Schlüssel mit Vollzugriff. |
| `403` `Domain not authorized` | Der Schlüssel ist auf eine andere Domain beschränkt als die der Adresse in `from`. | Senden Sie von der Domain des Schlüssels oder verwenden Sie einen anderen Schlüssel. |
| SMTP `535 Authentication failed` | Das Passwort ist kein gültiger API-Schlüssel. | Verwenden Sie den API-Schlüssel als Passwort und `emailit` als Benutzernamen. |

## Siehe auch

  - [Authentifizierung](/de/docs/api-reference/authentication/): So werden Anfragen authentifiziert.
  - [API für API-Schlüssel](/de/docs/api-reference/api-keys/): Schlüssel erstellen, auflisten, aktualisieren, neu generieren und löschen.
  - [SMTP-Einstellungen](/de/docs/smtp/settings/): Host, Ports, TLS und Zugangsdaten.
  - [Sicherheit](/de/docs/security/): Wie Emailit Ihr Konto und Ihre Daten schützt.

---
Quelle: https://emailit.com/de/docs/developers/api-keys/