EntwicklerAPI-Ressourcen

Rundmails

Eine Rundmail ist ein Text, der auf einmal per E-Mail an viele Empfänger:innen geht, so wie das Admin-Panel ihn unter Rundmail versendet. In der API ist eine Rundmail ein mailing. Sie geht an die Familien der Anmeldungen, die Sie nennen, an die Familien von Angeboten und Saisons, ausgewählt nach dem Status ihrer Anmeldungen, oder an die Mitglieder von Veranstalter-Profilen.

Endpunkte

POST/mailingsEine Rundmail versenden

Eine Rundmail zu versenden braucht ROLE_ADMIN. Für Rundmails an Familien kommt ROLE_PARTICIPANTS_ADMIN hinzu. Wer nach Zahlung filtern oder einen Zahlungslink einfügen will, braucht ROLE_PAYMENTS_ADMIN. Das Admin-Panel listet jede Rundmail an Teilnehmer:innen oder Veranstalter:innen auf der Seite Rundmail unter Zuletzt versendet auf.

Die Kopie an Sie selbst und die Zahlungsaufforderung an ausgewählte Familien versendet nur das Admin-Panel.

Das Modell der Rundmail

Name
uuid
Typ
string
Beschreibung
Der Versand. Der Postausgang des Admin-Panels listet die E-Mails der Rundmail darunter auf.
Name
subject
Typ
string
Beschreibung
Die Betreffzeile der E-Mails.
Name
recipients
Typ
integer
Beschreibung
Wie viele E-Mails hinausgehen: eine je E-Mail-Adresse.
Name
withoutEmail
Typ
integer
Beschreibung
Bei Rundmails an Anmeldungen: wie viele davon zu einer Familie ohne E-Mail-Adresse gehören. Bei Rundmails an Teilnehmer:innen: wie viele Teilnehmer:innen keine E-Mail-Adresse haben. Sie erreicht keine E-Mail.
Name
heldBack
Typ
integer
Beschreibung
Bei Rundmails an Teilnehmer:innen: wie viele ausgelassen wurden, weil sie die Verarbeitung ihrer Daten eingeschränkt oder der Direktwerbung widersprochen haben.
Name
attendances
Typ
array
Beschreibung
Bei Rundmails an Anmeldungen: die UUIDs der Anmeldungen, um die es in der Rundmail geht, jede einmal.

POST/mailings

Eine Rundmail versenden

Versendet eine Rundmail an die Zielgruppe, die to nennt: attendances, participants oder hosts. Jede Zielgruppe hat eigene Filter, alle auf der obersten Ebene des Bodys. Der Filter einer anderen Zielgruppe wird mit 422 abgewiesen. So erweitert ein Fehler nie den Kreis der Empfänger:innen.

Die E-Mails gehen im Hintergrund hinaus, eine je E-Mail-Adresse. Die API antwortet mit 202 Accepted und der Rundmail.

Attribute für jede Rundmail

Name
to
Typ
string
Beschreibung
Pflicht. An wen die Rundmail geht: attendances, participants oder hosts.
Name
text
Typ
string
Beschreibung
Pflicht. Der Text in Markdown: fett, kursiv, Listen und Links. Platzhalter wie {{ baseUrl }} werden für jede Empfänger:in ersetzt.
Name
subject
Typ
string
Beschreibung
Die Betreffzeile. Pflicht, außer bei einer Rundmail an attendances.
Name
attachment
Typ
object
Beschreibung
Ein PDF, das jede E-Mail enthält: {"filename": "Programm.pdf", "content": "<base64>"}, höchstens 6 MB.

An Anmeldungen

Jede Familie erhält eine E-Mail mit dem Text, gefolgt von ihren Anmeldungen unter den genannten und dem Status jeder Anmeldung. Anmeldungen werden nach Familie gruppiert: nach der E-Mail-Adresse der Teilnehmer:in, sonst nach der Adresse des Kontos der Teilnehmer:in. Das ist die E-Mail, die Anmeldungen festschreiben im Admin-Panel versendet. Versenden Sie sie, nachdem Sie die Entscheidungen einer Saison festgeschrieben haben, und nennen Sie die attendances, die dieser Aufruf geliefert hat.

Name
attendances
Typ
array
Beschreibung
Pflicht. Die UUIDs der Anmeldungen, mindestens eine. Eine unbekannte UUID wird mit 404 abgewiesen, und nichts wird versendet.

Ohne subject tragen die E-Mails den Betreff von Zulassungsbescheide unter Benachrichtigungen im Admin-Panel: die eigene Fassung der Saison, wenn alle Anmeldungen zu einer Saison gehören und sie eine hat, sonst die Standardfassung, sonst Ihre Anmeldungen.

Um die E-Mails später zu finden, listen Sie die gesendeten Nachrichten mit ?attendance=<uuid> auf.

An Teilnehmer:innen

Erreicht die Familien der Teilnehmer:innen von Angeboten und Saisons, ausgewählt nach dem Status ihrer Anmeldungen, wie Teilnehmende auf der Seite Rundmail.

Name
editions
Typ
array
Beschreibung
Die Familien dieser Saisons, als UUID oder Alias. Nennen Sie mindestens eine Saison oder ein Angebot.
Name
offers
Typ
array
Beschreibung
Die Familien dieser Angebote, als UUID.
Name
status
Typ
array
Beschreibung
Die Status der Anmeldungen, deren Familien erreicht werden. Der Standard ist ["confirmed", "unfulfilled"]. Einer oder mehrere von confirmed, participated, noshow, waiting, waitlisted, email_unconfirmed, consents_outstanding, unfulfilled, rejected, withdrawn.
Name
unacknowledged
Typ
boolean
Beschreibung
Nur Anmeldungen, die weder bezahlt noch anderweitig bestätigt sind. Der Standard ist false.
Name
unpaid
Typ
boolean
Beschreibung
Mit unacknowledged: nur Anmeldungen mit Beitrag. Der Standard ist false.
Name
paymentLink
Typ
boolean
Beschreibung
Mit unacknowledged: einen Beleg und einen Link zum Online-Bezahlen einfügen. Der Standard ist false.
Name
attendanceDetails
Typ
boolean
Beschreibung
Die Anmeldungen jeder Familie unter dem Text auflisten. Der Standard ist true.

An Veranstalter:innen

Erreicht die Konten der Mitglieder von Veranstalter-Profilen, wie Veranstaltende auf der Seite Rundmail. Ohne Filter erreicht sie die Mitglieder jedes Veranstalter-Profils.

Name
hosts
Typ
array
Beschreibung
Die Mitglieder dieser Veranstalter-Profile, als UUID oder Alias.
Name
editions
Typ
array
Beschreibung
Nur Veranstalter-Profile mit einem Angebot in diesen Saisons, als UUID oder Alias.
Name
withOffer
Typ
boolean
Beschreibung
Nur Veranstalter-Profile mit einem Angebot in irgendeiner Saison. Der Standard ist false, mit editions true.
Name
includeDisabled
Typ
boolean
Beschreibung
Auch deaktivierte Konten erreichen. Der Standard ist false.

Fehler

Status	Wann
`403`	Familien ohne `ROLE_PARTICIPANTS_ADMIN`; `unacknowledged` oder `paymentLink` ohne `ROLE_PAYMENTS_ADMIN`.
`404`	Eine Anmeldung, die es nicht gibt.
`409`	Eine Saison in der Auswahl verlangt von Veranstalter:innen eine Vertraulichkeitserklärung, und die Absender:in hat sie nicht unterzeichnet. Ein Service-Account kann sie nicht unterzeichnen und deshalb an eine solche Saison nichts senden.
`422`	Ein fehlendes oder unbekanntes `to`, ein Filter einer anderen Zielgruppe, ein fehlender `text` oder `subject`, keine Anmeldung oder keine Saison und kein Angebot, eine unbekannte Saison, ein unbekanntes Angebot, ein unbekanntes Veranstalter-Profil oder ein unbekannter Status, `unpaid` oder `paymentLink` ohne `unacknowledged`, `editions` mit `withOffer: false` an Veranstalter:innen oder ein Anhang, der kein PDF oder zu groß ist.

POST/mailings

curl -X POST https://example.fepli.eu/api/mailings \
  -H "Authorization: Bearer $FEPLI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "attendances",
    "attendances": [
      "0192d0e8-3a4b-7c5d-9e6f-7a8b9c0d1e07",
      "0192d0e8-3a4b-7c5d-9e6f-7a8b9c0d1e08"
    ],
    "text": "Die Plätze sind vergeben. Unten sehen Sie, wie über Ihre Anmeldungen entschieden wurde."
  }'

Antwort (202 Accepted)

{
  "uuid": "0199a3c4-7e21-7b50-9d8e-4f3a2b1c0d9e",
  "subject": "Treffpunkt geändert",
  "recipients": 14,
  "withoutEmail": 1,
  "heldBack": 0,
  "attendances": []
}