API-Dokumentation

Einführung

Fehlerformat

Bei Validierungsfehlern (422) gibt die API folgendes zurück:

// HTTP 422 Unprocessable Entity
{
  "message": "The given data was invalid.",
  "errors": {
    "email": ["The email field is required."]
  }
}

Autorisierungsfehler liefern 401 (nicht eingeloggt) oder 403 (keine Berechtigung).

Authentifizierung

Alle geschützten Endpunkte erfordern ein Sanctum-Token. Token werden pro Gerät ausgestellt und können jederzeit widerrufen werden.

// POST /api/auth/token
{
  "email": "nutzer@beispiel.de",
  "password": "geheim123",
  "device_name": "Mein Server"
}

{
  "token": "1|abc123xyz...",
  "user": {
    "id": 1,
    "name": "Max Mustermann",
    "email": "nutzer@beispiel.de"
  }
}

{
  "message": "Token wurde widerrufen."
}

Öffentliche Anmelde-API

Diese Endpunkte sind für eingebettete Anmeldeformulare konzipiert. Der {token} ist der subscribe_form_token einer Empfängerliste mit aktivierter öffentlicher Anmeldung.

{
  "name": "Newsletter Q4",
  "description": "Vierteljährlicher Überblick",
  "double_opt_in": true,
  "doi_subject": "Bitte bestätigen Sie Ihre Anmeldung"
}

// POST /api/subscribe/abc123
{
  "email": "maria@beispiel.de",
  "first_name": "Maria",
  "last_name": "Muster"
}

// Double-Opt-in aktiv
{ "status": "pending", "message": "Bitte bestätigen Sie Ihre Anmeldung per E-Mail." }

// Direkt eingetragen
{ "status": "subscribed", "message": "Erfolgreich angemeldet!" }

Teams

Ein Team bündelt alle Ressourcen (Anbieter, Listen, Kampagnen). Jeder Nutzer kann mehreren Teams angehören. Die aktuelle Team-Kontext wird über current_team_id im Nutzer-Profil gesteuert.

POST /api/teams — Request-Body

Antwort – Team-Objekt

{
  "id": 1,
  "name": "Mein Unternehmen",
  "slug": "mein-unternehmen-x7k2f1",
  "owner_id": 5,
  "members_count": 3,
  "created_at": "2024-01-15T10:00:00Z"
}

DELETE gibt 204 No Content zurück. Nur der Team-Eigentümer darf ein Team löschen (sonst 403).

E-Mail-Anbieter

Konfigurieren Sie SMTP, Amazon SES, Mailgun oder SendGrid als Versandanbieter. Alle Operationen sind auf das aktuelle Team beschränkt.

Request-Body (POST / PUT)

// POST /api/providers
{
  "name": "Mailgun EU",
  "type": "mailgun",
  "api_key": "key-xxxxxxxx",
  "api_region": "eu",
  "from_address": "noreply@meinedomain.de",
  "from_name": "Mein Newsletter",
  "active": true
}

Anbieter-Regeln

Versandlimits und Domain-Gruppen pro Anbieter. Regeln werden vom internen Throttling-System in Echtzeit ausgewertet.

Request-Body (POST)

PUT unterstützt partielle Aktualisierung (sometimes-Validierung). DELETE gibt 204 zurück.

Empfängerlisten

Listen bündeln Empfänger für Kampagnen. Jede Liste kann ein eigenes Double-Opt-in-Verfahren und einen öffentlichen Anmeldetoken besitzen.

Request-Body (POST / PUT)

// GET /api/lists — Antwort
[
  {
    "id": 3,
    "name": "Kunden-Newsletter",
    "double_opt_in": true,
    "public_subscribe": true,
    "subscribed_count": 1248,
    "updated_at": "2024-03-10T14:22:00Z"
  }
]

Empfänger

Empfänger werden einer Liste zugeordnet. Das Löschen eines Eintrags setzt den Status auf unsubscribed — der Datensatz bleibt für Auditzwecke erhalten.

POST — Einzelner Empfänger

POST /bulk — Request-Body

// POST /api/lists/3/recipients/bulk
{
  "recipients": [
    { "email": "anna@beispiel.de", "name": "Anna Schmidt" },
    { "email": "ben@beispiel.de" }
  ]
}

Antwort 200

{ "imported": 2, "skipped": 0 }

Ungültige E-Mail-Adressen werden stillschweigend übersprungen. Die Quelle wird für Importdatensätze als api bzw. api_bulk gespeichert.

Templates

E-Mail-Vorlagen mit automatischer Versionierung. Jede Aktualisierung erhöht die version-Zahl.

Request-Body (POST / PUT)

// GET /api/templates — Antwort (Listenformat)
[
  {
    "id": 7,
    "name": "Willkommens-Mail",
    "subject": "Herzlich willkommen!",
    "editor_type": "grapesjs",
    "is_published": true,
    "version": 3,
    "updated_at": "2024-04-01T09:15:00Z"
  }
]

Kampagnen

Eine Kampagne verknüpft Template + Empfängerliste + Anbieter und steuert den Versandprozess. Antworten enthalten den CampaignResource-Satz.

Request-Body (POST / PUT)

CampaignResource — Felder

{
  "id": 12,
  "name": "Frühjahrs-Aktion 2024",
  "status": "scheduled",
  "subject": "Jetzt sparen!",
  "schedule_at": "2024-04-15T08:00:00Z",
  "started_at": null,
  "completed_at": null,
  "provider_strategy": "round_robin",
  "total_recipients": 5200,
  "sent_count": 0,
  "delivery_rate": 0.0,
  "open_rate": 0.0,
  "click_rate": 0.0,
  "utm_tags": { "utm_source": "newsletter" },
  "list": { "id": 3, "name": "Kunden-Newsletter" },
  "template": { "id": 7, "name": "Willkommens-Mail" },
  "provider": { "id": 2, "name": "Mailgun EU", "type": "mailgun" },
  "created_at": "2024-04-01T12:00:00Z",
  "updated_at": "2024-04-01T12:00:00Z"
}

Kampagnen-Aktionen & Statistiken

// GET /api/campaigns/12/events?status=bounced
{
  "data": [
    {
      "id": 884,
      "status": "bounced",
      "bounce_type": "hard",
      "bounce_code": "550",
      "bounce_message": "User does not exist",
      "sent_at": "2024-04-15T08:02:11Z",
      "bounced_at": "2024-04-15T08:02:45Z",
      "recipient": { "id": 302, "email": "alt@beispiel.de", "name": null }
    }
  ],
  "links": { "next": "https://app.einfach-news.de/api/campaigns/12/events?page=2" }
}

{
  "total_recipients": 5200,
  "sent": 5188,
  "failed": 12,
  "opened": 1872,
  "clicked": 543,
  "bounced": 37,
  "complained": 2,
  "open_rate": 36.1,
  "click_rate": 10.5,
  "bounce_rate": 0.7,
  "delivery_rate": 99.8
}

Unterdrückungsliste

Unterdrückte E-Mail-Adressen oder Domains werden beim Kampagnenversand automatisch übersprungen. Paginiert mit 50 Einträgen pro Seite.

Request-Body (POST)

// POST /api/suppressions
{
  "email": "beschwerde@beispiel.de",
  "type": "email",
  "reason": "complaint",
  "notes": "Manuell nach Beschwerde gesperrt"
}

// PUT /api/suppressions/{id} — nur notes + expires_at änderbar
{
  "notes": "Bis Q3 gesperrt",
  "expires_at": "2024-09-30"
}