Zum Hauptinhalt springen

Dispatch API

Base URL: https://api.fwv-raura.ch

Die Dispatch API verwaltet E-Mail-Versand, Briefversand (Pingen), Newsletter, Kontaktformular, Mailcow-Integration, PDF-Vorlagen und Organisations-Einstellungen.

E-Mail-Vorlagen​

Vorlagen abrufen​

GET /templates
Authorization: Bearer <token>

Vorlage erstellen​

POST /templates
Authorization: Bearer <token>
Content-Type: application/json

{
"name": "Einladung GV",
"subject": "Einladung zur Generalversammlung",
"html": "<p>Liebe Mitglieder...</p>",
"text": "Liebe Mitglieder..."
}

Vorlage bearbeiten​

PUT /templates/:id
Authorization: Bearer <token>

Vorlage löschen​

DELETE /templates/:id
Authorization: Bearer <token>

E-Mail-Versand​

Einzelne E-Mail versenden​

POST /email/send
Authorization: Bearer <token>
Content-Type: application/json

{
"to": "empfaenger@example.com",
"subject": "Betreff",
"html": "<p>Nachricht</p>",
"text": "Nachricht als Plain-Text"
}

Massen-E-Mail versenden​

POST /email/bulk
Authorization: Bearer <token>
Content-Type: application/json

{
"member_ids": ["<uuid>", "<uuid>"],
"subject": "Rundschreiben",
"html": "<p>Liebe Mitglieder...</p>",
"template_id": 1
}

Intelligenter Versand​

POST /dispatch/smart
Authorization: Bearer <token>
Content-Type: application/json

{
"member_ids": ["<uuid>"],
"subject": "Einladung",
"html": "<p>...</p>"
}

Versendet automatisch per E-Mail oder Brief, je nach Zustellungspräferenz des Mitglieds.

Kontaktformular​

Kontaktformular absenden​

POST /contact
Content-Type: application/json

{
"name": "Max Muster",
"email": "max@example.com",
"message": "Nachricht..."
}

Sendet eine Bestätigungs-E-Mail an den Absender.

Kontaktanfrage bestätigen​

GET /contact/confirm/:token

Bestätigt die Kontaktanfrage per Token (Double-Opt-In).

Newsletter​

Newsletter abonnieren​

POST /newsletter/subscribe
Content-Type: application/json

{
"email": "max@example.com"
}

Abo bestätigen​

GET /newsletter/confirm?token=xxx

Newsletter abbestellen​

POST /newsletter/unsubscribe
Content-Type: application/json

{
"email": "max@example.com"
}

Mailcow-Integration​

Verwaltung von E-Mail-Postfächern und Aliases über die Mailcow-API.

Postfächer abrufen​

GET /mailcow/mailboxes
Authorization: Bearer <token>

Einzelnes Postfach​

GET /mailcow/mailboxes/:email
Authorization: Bearer <token>

Postfach erstellen​

POST /mailcow/mailboxes
Authorization: Bearer <token>
Content-Type: application/json

{
"local_part": "neues-postfach",
"name": "Neues Postfach",
"password": "xxx",
"quota": 1024
}

Postfach bearbeiten​

PUT /mailcow/mailboxes/:email
Authorization: Bearer <token>

Postfach löschen​

DELETE /mailcow/mailboxes/:email
Authorization: Bearer <token>

Aliases abrufen​

GET /mailcow/aliases
Authorization: Bearer <token>

Alias erstellen​

POST /mailcow/aliases
Authorization: Bearer <token>
Content-Type: application/json

{
"address": "alias@fwv-raura.ch",
"goto": "ziel@fwv-raura.ch"
}

Alias bearbeiten/löschen​

PUT /mailcow/aliases/:id
DELETE /mailcow/aliases/:id
Authorization: Bearer <token>

Domain-Info​

GET /mailcow/domain
Authorization: Bearer <token>

Speicherplatz-Status​

GET /mailcow/quota
Authorization: Bearer <token>

Post-Versand (Pingen)​

Konto-Informationen​

GET /pingen/account?staging=false
Authorization: Bearer <token>

Response:

{
"name": "Feuerwehrverein Raura",
"balance": 5000,
"currency": "CHF",
"isStaging": false
}

Statistiken​

GET /pingen/stats
Authorization: Bearer <token>

Response:

{
"total": 50,
"sent": 45,
"pending": 3,
"failed": 2,
"last_30_days": 15,
"last_7_days": 5
}

Alle Briefe abrufen​

GET /pingen/letters?event_id=<uuid>&member_id=<uuid>&limit=50
Authorization: Bearer <token>

Brief-Status​

GET /pingen/letters/:letterId/status?staging=false
Authorization: Bearer <token>

Response:

{
"letterId": "abc123",
"status": "sent",
"price": 125,
"pages": 2,
"sentAt": "2026-01-21T10:00:00Z"
}

Brief versenden​

POST /pingen/send
Authorization: Bearer <token>
Content-Type: application/json

{
"member_id": "<uuid>",
"pdf_base64": "<base64-encoded-pdf>",
"staging": false
}

Einzelbrief manuell senden​

POST /pingen/send-manual
Authorization: Bearer <token>
Content-Type: application/json

{
"member_id": "<uuid>",
"event_id": "<uuid>",
"subject": "Einladung GV",
"body": "Brieftext hier...",
"staging": false
}

Der Brief wird automatisch formatiert mit Absender, Adresse und Datum.

Arbeitsplan per Post senden​

POST /pingen/send-arbeitsplan
Authorization: Bearer <token>
Content-Type: application/json

{
"event_id": "<uuid>",
"member_id": "<uuid>",
"pdf_base64": "<base64-encoded-pdf>",
"staging": false
}

Mitglieder mit Post-Zustellung​

GET /pingen/post-members
Authorization: Bearer <token>

Response:

{
"count": 12,
"members": [
{
"id": "<uuid>",
"name": "Max Muster",
"address": "Musterstrasse 1, 4303 Kaiseraugst",
"strasse": "Musterstrasse 1",
"plz": "4303",
"ort": "Kaiseraugst"
}
]
}

Massen-PDF versenden​

POST /pingen/send-bulk-pdf
Authorization: Bearer <token>
Content-Type: application/json

{
"pdf_base64": "<base64-encoded-pdf>",
"subject": "Einladung GV 2026",
"member_ids": ["<uuid>", "<uuid>"],
"staging": false
}

Wenn member_ids nicht angegeben wird, wird das PDF an alle Mitglieder mit zustellung_post = true gesendet.

Response:

{
"totalRecipients": 12,
"successCount": 11,
"failedCount": 1,
"success": [
{ "name": "Max Muster", "letterId": "abc123" }
],
"failed": [
{ "name": "Hans Mueller", "error": "Invalid address" }
],
"staging": false
}

Webhooks (Pingen)​

Registrierte Webhooks abrufen​

GET /pingen/webhooks?staging=false
Authorization: Bearer <token>

Webhook registrieren​

POST /pingen/webhooks/register
Authorization: Bearer <token>
Content-Type: application/json

{
"webhook_url": "https://api.fwv-raura.ch/pingen/webhook",
"staging": false
}

Webhook löschen​

DELETE /pingen/webhooks/:id?staging=false
Authorization: Bearer <token>

Webhook-Empfang (von Pingen)​

POST /pingen/webhook
Content-Type: application/json

{
"data": { "id": "letterId", "attributes": { "status": "sent" } },
"meta": { "event": "letter.status_changed" }
}

Empfängt automatische Status-Updates von Pingen und aktualisiert den Status in der Datenbank.

PDF-Vorlagen​

Verwaltung von PDF-Vorlagen für Briefe, Rechnungen und andere Dokumente. Die Vorlagen werden im PDF-Designer visuell bearbeitet.

Alle Vorlagen​

GET /pdf-templates
Authorization: Bearer <token>

Vorlage abrufen​

GET /pdf-templates/:id
Authorization: Bearer <token>

Vorlage erstellen​

POST /pdf-templates
Authorization: Bearer <token>
Content-Type: application/json

{
"name": "Rechnung Standard",
"category": "rechnung",
"layout": { ... }
}

Vorlage bearbeiten​

PUT /pdf-templates/:id
Authorization: Bearer <token>

Vorlage löschen​

DELETE /pdf-templates/:id
Authorization: Bearer <token>

Aktives PDF-Layout​

GET /pdf-templates/layout/active
Authorization: Bearer <token>

Gibt das aktuell aktive Layout (z.B. Briefkopf) zurück.

Rechnungen​

Rechnung mit QR-Code generieren​

POST /invoices/generate-qr
Authorization: Bearer <token>
Content-Type: application/json

{
"member_id": "<uuid>",
"amount": 50.00,
"description": "Jahresbeitrag 2026"
}

Generiert eine Swiss QR-Bill (Einzahlungsschein) als PDF.

Massen-Rechnungen generieren​

POST /invoices/generate-bulk
Authorization: Bearer <token>
Content-Type: application/json

{
"member_ids": ["<uuid>", "<uuid>"],
"amount": 50.00,
"description": "Jahresbeitrag 2026"
}

Organisations-Einstellungen​

Einstellungen abrufen​

GET /organisation-settings
Authorization: Bearer <token>

Einstellung aktualisieren​

PUT /organisation-settings/:key
Authorization: Bearer <token>
Content-Type: application/json

{
"value": "Neuer Wert"
}

Versand-Protokoll​

Versand-Historie​

GET /dispatch-log?type=email&status=sent&limit=100
Authorization: Bearer <token>

Query Parameter:

  • type - Filter nach Typ (email, pingen)
  • status - Filter nach Status (sent, pending, failed)
  • member_id - Filter nach Mitglied
  • event_id - Filter nach Event
  • limit - Anzahl Ergebnisse (Standard: 100)

Staging-Modus​

Alle Pingen-Endpoints unterstützen einen staging Parameter:

  • staging=false (Standard): Briefe werden tatsächlich versendet und Kosten entstehen
  • staging=true: Briefe werden nur in der Testumgebung verarbeitet, keine echten Kosten

Im Vorstand-Dashboard kann der Staging-Modus über einen Toggle aktiviert werden. Die Umgebungsvariable PINGEN_STAGING setzt den Standard-Wert.