API resources

Mailings

A mailing is a Rundmail: one text, e-mailed to many recipients at once, as the admin sends it under Rundmail. It goes to the families of attendances you name, to the families of offers and editions picked by the status of their attendances, or to the members of hosts.

Sending a mailing needs ROLE_ADMIN. Mailing families also needs ROLE_PARTICIPANTS_ADMIN, and filtering by payment or adding a payment link needs ROLE_PAYMENTS_ADMIN. The admin lists every mailing to participants or hosts under Zuletzt versendet on the Rundmail page.

The copy to yourself and the payment request to chosen families are sent in the admin only.

The mailing model

Name
uuid
Type
string
Description
The dispatch. The admin's Postausgang lists the mailing's e-mails under it.
Name
subject
Type
string
Description
The subject line the e-mails carry.
Name
recipients
Type
integer
Description
How many e-mails go out: one per e-mail address.
Name
withoutEmail
Type
integer
Description
To attendances: how many of them belong to a family without an e-mail address. To participants: how many participants have no e-mail address. No e-mail reaches them.
Name
heldBack
Type
integer
Description
To participants: how many were left out because they restricted the processing of their data or objected to direct marketing.
Name
attendances
Type
array
Description
To attendances: the UUIDs of the attendances the mailing is about, each once.

POST/mailings

Send a mailing

Sends a Rundmail to the audience to names: attendances, participants or hosts. Each audience has its own filters, all at the top level of the body. A filter of another audience is refused with 422, so a mistake never widens who gets the mail.

The e-mails go out in the background, one per e-mail address. The API answers 202 Accepted with the mailing.

Attributes for every mailing

Name
to
Type
string
Description
Required. Whom the mailing goes to: attendances, participants or hosts.
Name
text
Type
string
Description
Required. The text, in Markdown: bold, italic, lists and links. Placeholders such as {{ baseUrl }} are replaced for each recipient.
Name
subject
Type
string
Description
The subject line. Required, except for a mailing to attendances.
Name
attachment
Type
object
Description
A PDF every e-mail carries: {"filename": "Programm.pdf", "content": "<base64>"}, at most 6 MB.

To attendances

Each family gets one e-mail with the text, followed by its attendances among the ones named and the status of each. Attendances are grouped by family: by the participant's e-mail address, else by the address of the participant's account. This is the e-mail Anmeldungen festschreiben sends in the admin. Send it after you commit an edition's decisions, naming the attendances that call returned.

Name
attendances
Type
array
Description
Required. The UUIDs of the attendances, at least one. An unknown UUID is refused with 404, and nothing is sent.

Without a subject, the e-mails carry the subject of Zulassungsbescheide under Benachrichtigungen in the admin: the edition's own version where all attendances belong to one edition and it has one, else the standard version, else Ihre Anmeldungen.

To find the e-mails later, list the sent messages with ?attendance=<uuid>.

To participants

Reaches the families of the participants of offers and editions, picked by the status of their attendances, as Teilnehmende does on the Rundmail page.

Name
editions
Type
array
Description
The families in these editions, by UUID or alias. Name at least one edition or offer.
Name
offers
Type
array
Description
The families in these offers, by UUID.
Name
status
Type
array
Description
The statuses of the attendances whose families are reached. Defaults to ["confirmed", "unfulfilled"]. One or more of confirmed, participated, noshow, waiting, waitlisted, email_unconfirmed, consents_outstanding, unfulfilled, rejected, withdrawn.
Name
unacknowledged
Type
boolean
Description
Only attendances neither paid nor otherwise acknowledged. Defaults to false.
Name
unpaid
Type
boolean
Description
With unacknowledged: only attendances with a fee. Defaults to false.
Name
paymentLink
Type
boolean
Description
With unacknowledged: add a receipt and a link to pay online. Defaults to false.
Name
attendanceDetails
Type
boolean
Description
List each family's attendances below the text. Defaults to true.

To hosts

Reaches the accounts of hosts' members, as Veranstaltende does on the Rundmail page. Without filters, it reaches the members of every host.

Name
hosts
Type
array
Description
The members of these hosts, by UUID or alias.
Name
editions
Type
array
Description
Only hosts with an offer in these editions, by UUID or alias.
Name
withOffer
Type
boolean
Description
Only hosts with an offer in any edition. Defaults to false, or to true with editions.
Name
includeDisabled
Type
boolean
Description
Also reach disabled accounts. Defaults to false.

Errors

Status	When
`403`	Families without `ROLE_PARTICIPANTS_ADMIN`; `unacknowledged` or `paymentLink` without `ROLE_PAYMENTS_ADMIN`.
`404`	An attendance that does not exist.
`409`	An edition in the selection asks for the hosts' confidentiality declaration, and the sender has not signed it. A service account cannot sign it, so it cannot send to such an edition.
`422`	A missing or unknown `to`, a filter of another audience, a missing `text` or `subject`, no attendance or no edition or offer, an unknown edition, offer, host or status, `unpaid` or `paymentLink` without `unacknowledged`, `editions` with `withOffer: false` to hosts, or an attachment that is no PDF or is too large.

Request

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."
  }'

Response (202 Accepted)

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