API‑Key

Für den Zugriff auf die mail2many API ist der API‑Key entscheidend. Ein API‑Key authentifiziert deine Anwendung und gewährt Zugriff auf genau einen Account.

API‑Keys erstellen und verwalten

Ein Account kann mehrere API‑Keys mit unterschiedlichen Berechtigungen besitzen. Damit lassen sich verschiedene Keys für unterschiedliche Zwecke oder Drittanbieter‑Anwendungen verwenden:

Account 1 (Kunde A)
│
├─ API-Key "Webseite": abc123.1a2b3c4d5e6f...
│  └─ Berechtigungen: Empfänger
│
├─ API-Key "CRM": xyz789.7x8y9z1a2b3c...
│  └─ Berechtigungen: Empfänger
│
└─ API-Key "Kampagnen-Tool": def567.5d6e7f8a9b0c...
   └─ Berechtigungen: Artikel

Wenn du einen Admin‑Benutzer im mail2many‑Account hast, kannst du im Bereich Einstellungen API‑Keys anlegen. Andernfalls bitte einen Admin, einen API‑Key zu erstellen.

Berechtigungen

Jeder API‑Key hat einen Satz an Berechtigungen, die den Zugriff auf den Account einschränken. Diese Berechtigungen werden beim Erstellen festgelegt und können jederzeit geändert werden.

API-Scopes

API-Scopes definieren, auf welche Ressourcen ein API-Key zugreifen darf:

• Artikel (articles) Artikel anlegen und aktualisieren.

• Empfänger (subscribers) Empfänger anlegen und aktualisieren

Erweiterte Rechte

Zusätzlich zu den Scopes können API-Keys spezielle Rechte erhalten:

• "Archiviert, abgemeldet" auf Empfangsbereit ändern Erlaubt das Reaktivieren von abgemeldeten Empfängern über die API.

• "Archiviert, manuell" auf Empfangsbereit ändern Erlaubt das Reaktivieren von manuell archivierten Empfängern.

• "Archiviert, Spam-Beschwerde" auf Empfangsbereit ändern Erlaubt das Reaktivieren von Empfängern mit Spam-Beschwerden.

• "Empfangsbereit" archivieren Erlaubt das Archivieren von empfangsbereiten Empfängern.

• Unbekannte Empfänger bei Triggersendungen erlauben Erlaubt das Versenden an Empfänger, die noch nicht im System vorhanden sind.

Standard Opt-In Sendung

Am API-Key wird die Standard Opt-In Sendung festgelegt. Diese Sendung wird automatisch versendet, wenn über die API ein neuer Empfänger mit Opt-In-Anforderung angelegt wird.

info

Wichtig: Die Standard Opt-In Sendung ist relevant, wenn neue Empfänger über die API hinzugefügt werden und eine Bestätigung ihrer E-Mail-Adresse erforderlich ist (Double Opt-In).

Die Opt-In Sendung kann beim Erstellen des API-Keys ausgewählt oder später in den Einstellungen angepasst werden.

Sicherheit

info

Wichtig: Da der API‑Key vollen Zugriff auf den Account ermöglicht, muss er geheim bleiben. Behandle ihn wie ein Passwort!

• Übertrage den API‑Key nur über sichere Kanäle (HTTPS)
• Speichere ihn sicher und niemals im Code oder in öffentlichen Repositories
• Bei Verdacht auf Kompromittierung lösche den Key sofort und erstelle einen neuen
• Verwende verschiedene Keys für verschiedene Anwendungen, um die Sicherheit zu erhöhen

API‑Key Format

Der API‑Key hat immer ein Präfix, gefolgt von einem Punkt und dem eindeutigen Key:

{PREFIX}.{UNIQUE_KEY}

Beispiel: abc123.1a2b3c4d5e6f...

Das Präfix ist eindeutig und hilft bei der Identifizierung des API-Keys.

Authentifizierung

Der API‑Key wird als Passwort im Basic‑Auth‑Header gesendet. Der Benutzername kann beliebig sein (z.B. mail2many oder api verwenden):

curl -X GET "https://YOUR_SERVER-api.mail2many.de/api/v1/subscribers" \
  --user 'mail2many:YOUR_API_KEY' \
  -H "Content-Type: application/json" \
  -H "Accept: application/json"

Der Basic‑Auth‑Header muss bei jeder Anfrage mitgesendet werden.

Account prüfen

Wenn du prüfen möchtest, auf welchen Account dein API‑Key zugreift, nutze die Route /whoami:

curl -X GET "https://YOUR_SERVER-api.mail2many.de/api/v1/whoami" \
  --user 'mail2many:YOUR_API_KEY' \
  -H "Content-Type: application/json" \
  -H "Accept: application/json"

Diese Route gibt Informationen über den Account zurück, auf den der API‑Key Zugriff hat.