REST API · v1

Ein Token. Jeder Endpoint.

Eine schlanke, ressourcenorientierte HTTP API für Kampagnen, Listen, Abonnenten, Automatisierungen, Sending Server und Kundenabrechnung. Authentifizieren Sie sich mit einem einzigen Token, fragen Sie JSON ab, liefern Sie in Minuten aus. Dieselbe API, die Plugins nutzen, ist dieselbe API, die externe Clients nutzen — keine Endpoints zweiter Klasse.

Schnellstart in 4 Schritten ↓ Endpoint-Katalog

Was Sie damit bauen können

SaaS-Frontend Mobile App CRM-Sync Automatisierungs-Trigger Reseller-Dashboards

WARUM DIESE API

Keine Überraschungen. Keine Endpoints zweiter Klasse.
Dieselbe API, die Ihre Plugins nutzen.

Token-authentifiziert

Jeder Request trägt einen einzigen Bearer Token. Wird pro Benutzer aus Profil → API-Token erzeugt. Übergeben Sie ihn via Authorization: Bearer-Header oder ?api_token=-Query-String. Jederzeit widerrufbar und rotierbar.

Ressourcenorientiert

Jedes Konzept ist eine Ressource mit vorhersagbaren Verben. GET /lists gibt die Collection zurück, POST /lists erzeugt eine, PATCH /lists/:uid aktualisiert, DELETE /lists/:uid entfernt. Unter-Ressourcen verschachteln sich natürlich: /lists/:uid/subscribers.

Identisch mit Plugin-API

Es gibt keine Trennung zwischen intern und extern. Die Endpoints, die AcelleMail’s eigene UI aufruft, die Endpoints, die Ihr Plugin erweitert, und die Endpoints, die Ihr externer Client liest — identisch. Plugin-SDK ansehen →

Selbstgehosteter Endpoint

Die Basis-URL ist Ihr eigener Server — https://your-acelle.example.com/api/v1/. Kein Anbieter-Proxy, kein geteiltes Rate-Limit, keine Gebühr pro Request. Der Durchsatz entspricht dem, was Ihre Hardware hergibt.

SCHNELLSTART

Von null bis zur ersten Antwort in vier Schritten.

Jede AcelleMail-Installation hostet ihre eigene API unter /api/v1/. Ersetzen Sie your-acelle.example.com durch den Hostnamen Ihrer Installation.

STEP 1

Token erzeugen

Melden Sie sich in Ihrer AcelleMail-Installation an. Öffnen Sie das Profilmenü und klicken Sie auf API-Token. Kopieren Sie den Wert — er ist pro Benutzer eindeutig und an dessen Berechtigungen gebunden.

# In your shell:
$ export ACELLE_TOKEN=paste-your-token-here
$ export ACELLE_BASE=https://your-acelle.example.com

STEP 2

Token verifizieren

Rufen Sie /me auf. Ist der Token gültig, erhalten Sie Ihren Benutzerdatensatz zurück. Andernfalls erhalten Sie ein 401 — prüfen Sie Token und Basis-URL.

$ curl $ACELLE_BASE/api/v1/me \
    -H "Authorization: Bearer $ACELLE_TOKEN"

{ "id": 1, "email": "you@…", "uid": "…" }

STEP 3

Liste anlegen

Ressourcen werden mit POST erzeugt. Die Pflichtfelder im Body einer Mailingliste sind name, from_email, from_name, subject sowie ein Kontaktblock.

$ curl -X POST $ACELLE_BASE/api/v1/lists \
    -H "Authorization: Bearer $ACELLE_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "name":       "Newsletter",
      "from_name":  "Acme",
      "from_email": "hi@acme.com",
      "subject":    "Welcome"
    }'

STEP 4

Abonnenten hinzufügen

Verwenden Sie die UID der Liste aus Schritt 3. Custom Fields werden als Großbuchstaben-Parameter übergeben (FIRST_NAME, LAST_NAME, …) — passend zur Feldkonfiguration Ihrer Liste.

$ curl -X POST $ACELLE_BASE/api/v1/subscribers \
    -H "Authorization: Bearer $ACELLE_TOKEN" \
    -d list_uid=$LIST_UID \
    -d EMAIL=alice@example.com \
    -d FIRST_NAME=Alice \
    -d tag=newsletter,beta

RESSOURCEN

Acht Ressourcen. Über vierzig Endpoints. Jedes Verb, das Sie erwarten.

Alle Endpoints unten liegen im Namespace /api/v1/ und erfordern eine auth:api-Token-Authentifizierung, sofern nicht anders angegeben. Lifecycle-Aktionen (run, pause, resume) sind als POST-Sub-Routen exponiert. Log-Downloads streamen das zugrunde liegende CSV.

Authentifizierung

Alle authentifizierten Endpoints akzeptieren den Token entweder via Authorization: Bearer-Header (bevorzugt) oder via ?api_token=-Query-Parameter (Legacy). Nutzen Sie POST /user/login, um E-Mail/Passwort aus einem programmatischen Client gegen einen frischen Token zu tauschen.

POST/user/loginTauscht E-Mail + Passwort gegen einen API-Token. Öffentlicher Endpoint.

GET/meGibt den Datensatz des authentifizierten Benutzers zurück. Zur Verifikation eines Tokens nutzen.

POST/login-tokenErzeugt eine Einmal-Login-URL, über die der Benutzer authentifiziert landet.

Lists

Mailinglisten sind der primäre Container für Abonnenten. Jede Liste bringt eine Standard-Absenderidentität, Custom Fields sowie Double-Opt-in- / Welcome-E-Mail-Einstellungen mit. Custom Fields werden über die Sub-Route add-field ergänzt.

GET/listsPaginierter Index der Listen, die dem Token-Benutzer gehören.

POST/listsLegt eine neue Liste an. Erforderlich: name, from_email, from_name, subject + Kontaktblock.

GET/lists/:uidLädt eine einzelne Liste mit ihren Feldern und Statistiken.

PATCH/lists/:uidAktualisiert Listen-Metadaten, Absenderidentität oder Opt-in-Einstellungen.

POST/lists/:uid/add-fieldFügt ein Custom Field hinzu. Typ ist text, number oder datetime.

DELETE/lists/:uidLöscht eine Liste samt allen Abonnenten dauerhaft.

Subscribers

Abonnenten gehören zu einer Liste und tragen Werte für Custom Fields, Tags sowie eine Öffnungs- und Klick-Historie. Der Status ist einer von subscribed, unsubscribed oder unconfirmed. Tag-Operationen sind additiv und idempotent.

GET/subscribers?list_uid=…Paginierter Index. Filtern Sie mit open=yes|no, click=yes|no.

POST/subscribersAnlegen. Erforderlich: list_uid, EMAIL. Custom Fields als Großbuchstaben-Parameter.

GET/subscribers/:idLädt einen einzelnen Abonnenten nach ID oder E-Mail.

GET/subscribers/email/:emailFindet jede Liste, die einen Abonnenten mit dieser E-Mail enthält.

PATCH/subscribers/:idAktualisiert Felder, Tags oder Status.

POST/subscribers/:id/add-tagFügt kommagetrennte Tags hinzu.

POST/subscribers/:id/remove-tagEntfernt kommagetrennte Tags.

PATCH/lists/:list_uid/subscribers/:id/subscribeMarkiert als subscribed.

PATCH/lists/:list_uid/subscribers/:id/unsubscribeMarkiert als unsubscribed.

PATCH/lists/:list_uid/subscribers/email/:email/unsubscribeAbmeldung per E-Mail, wenn Sie die ID nicht haben.

DELETE/subscribers/:idHartes Löschen aus der Liste.

Campaigns

Kampagnen sind die Versandeinheit. Legen Sie eine mit HTML-Inhalt + Tracking-Flags an, durchlaufen Sie run / pause / resume und laden Sie anschließend Tracking-, Open-, Click-, Bounce-, Feedback- und Abmelde-Logs als CSV herunter.

GET/campaignsPaginierter Index. Übergeben Sie per_page, page.

POST/campaignsAnlegen. Erforderlich: list_uid, name, subject, from_*, html.

GET/campaigns/:uidLädt eine einzelne Kampagne mit Statistiken.

PATCH/campaigns/:uidAktualisiert Inhalt, Betreff oder Tracking-Flags.

POST/campaigns/:uid/runStellt die Kampagne zur Auslieferung in die Queue.

POST/campaigns/:uid/pausePausiert eine laufende Kampagne.

POST/campaigns/:uid/resumeSetzt eine pausierte Kampagne fort.

GET/campaigns/:uid/tracking-log/downloadStreamt das Tracking-CSV.

GET/campaigns/:uid/{open,click,bounce,feedback,unsubscribe}-log/downloadStreamt das Per-Event-CSV (eine Route pro Event-Typ).

DELETE/campaigns/:uidLöscht eine Kampagne (nur wenn nicht in Bearbeitung).

Automations

Automatisierungen sind visuelle Flows aus Triggern, Bedingungen und Aktionen. Die API exponiert die Read-Sicht plus zwei Wege, Flows aus externen Systemen zu zünden: execute, um eine ganze Automatisierung laufen zu lassen, oder api/call, um einen "API call"-Node mitten im Flow zu triggern.

GET/automationsIndex der Automatisierungen, die dem Token-Benutzer gehören.

POST/automations/:uid/executeTriggert eine Automatisierung für einen Abonnenten. Nützlich für transaktionale Flows.

POST/automations/:uid/api/callZündet einen "API call"-Trigger-Node mitten im Flow mit individuellem Payload.

Sending servers

Sending Server sind die konfigurierbaren Transporte (SMTP, Amazon SES, SendGrid, Mailgun, Postmark, individuelle Driver aus Plugins). Verwalten Sie sie programmatisch beim Provisionieren neuer Tenants oder beim Rotieren von Credentials.

GET/sending_serversIndex der konfigurierten Sending Server.

POST/sending_serversLegt einen neuen Sending Server an. Driver-spezifische Konfiguration unter settings.

GET/sending_servers/:uidLädt einen einzelnen Sending Server.

PATCH/sending_servers/:uidAktualisiert Einstellungen oder rotiert Credentials.

DELETE/sending_servers/:uidEntfernt einen Sending Server (referenzierende Kampagnen müssen vorher umgeleitet werden).

Einen neuen Transport hinzuzufügen (Postal MTA, individuelle HTTP API, …) läuft über einen REGISTRY-Hook — liefern Sie ihn als Plugin aus, statt den Core zu patchen.

Customers ADMIN

Customer-Endpoints sind Admin-Tokens vorbehalten. Nutzen Sie sie zum Provisionieren von Tenant-Accounts, zum Verwalten von Subscriptions, zum Wechseln von Plänen oder zum Erzeugen von Einmal-Login-URLs für Support/Impersonation.

GET/customersPaginierter Index aller Customers.

POST/customersLegt einen neuen Customer + Benutzeraccount an.

GET/customers/by-email/:emailSchlägt einen Customer per E-Mail nach.

PATCH/customers/:uidAktualisiert Customer-Profil / Kontakt / Quota.

PATCH/customers/:uid/{enable,disable}Sperrt oder reaktiviert den Zugriff, ohne Daten zu löschen.

POST/customers/:uid/change-plan/:plan_uidWechselt einen Customer auf einen anderen Plan (Belastungen, Proration, Subscription-Verlängerung).

POST/customers/:uid/assign-plan/:plan_uidWeist einen Plan ohne Abrechnungsfluss zu (Admin-Override).

POST/customers/:uid/subscription/updateAktualisiert die Parameter einer aktiven Subscription.

POST/login-tokenErzeugt eine Einmal-Login-URL für den Ziel-Customer.

Subscriptions ADMIN

Subscriptions verknüpfen einen Customer mit einem Plan + einer Abrechnungs-Kadenz. Nutzen Sie diese Endpoints, wenn Sie externe Billing-Systeme integrieren oder wiederkehrende Umsätze auditieren.

GET/subscriptionsIndex aller aktiven Subscriptions.

POST/subscriptionsLegt einen Subscription-Datensatz an (typischerweise vom Webhook Ihres Gateways getrieben).

GET/subscriptions/:uidLädt eine einzelne Subscription mit ihrer Verlängerungshistorie.

PATCH/subscriptions/:uidPasst Quota, Kadenz oder Enddatum an.

Files

Laden Sie Bilder und andere Assets zur Verwendung in Kampagneninhalten hoch. Der Endpoint akzeptiert multipart/form-data und liefert eine öffentliche URL, die Sie im HTML-Body referenzieren können.

POST/file/uploadLädt eine Datei hoch. Gibt { "url": "..." } zurück.

Plugins & Upgrades ADMIN

Installieren Sie Plugins programmatisch über eine Download-URL, führen Sie Remote-Core-Upgrades in einem zweistufigen Request-Flow aus (damit Schritt 2 auf einem frischen PHP-Worker landet), oder aktualisieren Sie die Lizenz. Nützlich für Flottenbetreiber, die viele AcelleMail-Tenants verwalten.

POST/plugins/installInstalliert ein Plugin über eine Download-URL.

POST/upgrade/runStartet ein Remote-Core-Upgrade (Download + Extraktion).

POST/upgrade/run-fileWendet einen einzelnen Migrations-Schritt an.

POST/upgrade/finalizeSchließt ein Upgrade ab. Muss als frischer Request nach run aufgerufen werden.

POST/license/refreshAktualisiert die CodeCanyon-Lizenzinformationen (spiegelt Admin → License).

WEBHOOKS

Events herauspushen, statt sie zu pollen.

AcelleMail bringt zwei Webhook-Oberflächen mit. Lifecycle-Webhooks feuern bei Customer-, Subscription- und Automation-Übergängen und werden global konfiguriert. Per-Recipient-Tracking-Pings feuern bei Opens / Clicks / Abmeldungen und werden pro Kampagne konfiguriert. Beide retrien im Fehlerfall mit exponentiellem Backoff.

Lifecycle-Webhooks

Customer- + Subscription-Übergänge

Einmalig konfiguriert unter Admin → Settings → Webhooks. Jeder Webhook besteht aus Name + Event + ausgehender HTTP-Konfiguration (URL, Methode, Header, Body-Template). Sechs Events sind im Core enthalten:

new_customer — params: customer_id
new_subscription — customer_id, plan_id
change_plan — customer_id, old_plan_id, new_plan_id
cancel_subscription — customer_id, plan_id
terminate_subscription — customer_id, plan_id
automation_webhook — automation_id (feuert aus API call-Nodes)

Die Retry-Policy ist pro Webhook: konfigurierbares retry_times (Default 2) und retry_after_seconds (Default 900). Fehlgeschlagene Zustellungen werden geloggt, retried und im Admin-Webhook-Log angezeigt.

Plugins können über das EVENT-Hook-Pattern zusätzliche Events registrieren — acelle/ai etwa feuert ai_task_completed aus seinen eigenen Listenern.

Per-Recipient-Tracking

Opens, Clicks, Abmeldungen

Konfiguriert pro Kampagne oder pro E-Mail-Template unter Tracking → Webhooks. Drei Event-Typen feuern, sobald der Empfänger mit der Nachricht interagiert:

open — Empfänger hat die E-Mail geöffnet (Tracking-Pixel)
click — Empfänger hat einen getrackten Link geklickt
unsubscribe — Empfänger hat den Abmelde-Link geklickt

Jeder Ping trägt die Campaign-UID, die Abonnenten-E-Mail und die Click-URL (bei click-Events). Konfigurieren Sie so viele Tracking-Webhooks pro Kampagne wie nötig — nützlich für paralleles Mirroring zu Analytics + CRM + Data Warehouse.

Sending-Server-Events (Bounce, Complaint, Delivery) laufen über den internen Listener-Stack App\SendingServers\Webhooks\* — ausgewiesen über die Campaign-Log-Endpoints statt als ausgehende Webhooks. Log-CSVs herunterladen →

Beispiel: `new_subscription`-Payload

POST /your-webhook-url
Content-Type: application/json
X-AcelleMail-Event: new_subscription
X-AcelleMail-Signature: sha256=…

{
  "event":       "new_subscription",
  "customer_id": 1234,
  "plan_id":     "extended-monthly",
  "fired_at":    "2026-05-06T12:34:56Z"
}

Beispiel: `click`-Tracking-Payload

POST /your-webhook-url
Content-Type: application/json
X-AcelleMail-Event: click

{
  "event":         "click",
  "campaign_uid":  "abc123",
  "subscriber":    "alice@example.com",
  "url":           "https://acme.com/promo",
  "clicked_at":    "2026-05-06T12:34:56Z"
}

RESPONSES & FEHLER

Vorhersagbares JSON. Konventionelle Status-Codes.

Jede erfolgreiche Response ist JSON. Jede fehlgeschlagene Response ist JSON, mit einer message auf oberster Ebene und einer errors-Map bei Validierungsfehlern. Status-Codes folgen der REST-Konvention — Sie können Ihren Client allein auf den Code verzweigen.

Code	Wann Sie ihn sehen
200 OK	Erfolgreiches Lesen oder Aktualisieren.
201 Created	Erfolgreiches Anlegen.
401 Unauthorized	Token fehlt oder ist ungültig.
403 Forbidden	Token gültig, aber die Ressource gehört Ihnen nicht / kein Admin.
404 Not Found	UID existiert nicht.
422 Unprocessable	Validierungsfehler. Prüfen Sie die `errors`-Map im Body.
500 Server	Bug auf Server-Seite. Prüfen Sie `storage/logs/laravel.log`.

Validierungsfehler (422)

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "message": "The given data was invalid.",
  "errors": {
    "from_email": [
      "The from_email field is required."
    ],
    "subject": [
      "The subject must be at most 998 characters."
    ]
  }
}

Authentifizierungsfehler (401)

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{ "message": "Unauthenticated." }

Pagination

Index-Endpoints akzeptieren per_page (Default 10–25 je nach Ressource) und page. Responses enthalten die Standard-Form des Laravel-Paginators: data[], links, meta.current_page, meta.total.

Rate-Limits

Das Rate-Limiting liegt in Ihrer Hand — setzen Sie es in Ihrer Laravel-Installation über RouteServiceProvider. Stock-Builds liefern keinen API-Throttle aus, da Sie auf Ihren eigenen Server zugreifen. Ergänzen Sie throttle:60,1, falls Sie einen möchten.

Versionierung

Die aktuelle Major-Version ist v1. Neue Endpoints werden frei ergänzt; Breaking Changes an bestehenden Endpoints kämen als v2 neben v1. Pinnen Sie Ihren Client auf /api/v1/ und Sie sind stabil.

CLIENTS

Jeder HTTP-Client. Kein proprietäres SDK.

Es gibt kein AcelleMail-SDK zu installieren. Die API spricht JSON über HTTP — greifen Sie zu dem Client, den Ihr Stack ohnehin schon hat. Drei der gängigsten in der Praxis:

curl · Einzeiler

curl $ACELLE_BASE/api/v1/lists \
  -H "Authorization: Bearer $ACELLE_TOKEN" \
  | jq '.data[].name'

Laravel HTTP-Client

$resp = Http::withToken($token)
    ->baseUrl($base.'/api/v1')
    ->post('/subscribers', [
        'list_uid' => $listUid,
        'EMAIL'    => $email,
    ]);

return $resp->json();

Browser- / Node-fetch

const r = await fetch(
  `${base}/api/v1/campaigns/${uid}/run`,
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
    },
  }
);
const data = await r.json();

Sie bauen ein Open-Source-SDK? Schreiben Sie uns — wir verlinken es von dieser Seite.

KANONISCHE REFERENZ

Die vollständige, ausführbare API-Referenz.

Jeder Parameter. Jede Rückgabe-Form. Jedes funktionierende curl-Beispiel. Gehostet auf der kanonischen Demo-Installation — derselbe Code, den Ihre Installation ausführt.

api.acellemail.com

Ersetzen Sie api.acellemail.com beim Aufruf durch den Hostnamen Ihrer eigenen Installation.

RESSOURCEN & COMMUNITY

Bauen Sie mit der API, liefern Sie als Plugin, fragen Sie, wenn Sie feststecken.

JETZT LOSBAUEN

Starten Sie AcelleMail. Holen Sie sich einen Token. Setzen Sie einen Call ab.

Einmalige Lizenz. Vollständiger Quellcode. Selbstgehosteter Endpoint. Die API ist enthalten — kein Add-on, kein Tarifplan.

AcelleMail sichern — $80 Plugin-SDK →