# Nachrichten

E-Mails an Gäste entwerfen, planen, senden und Kontingente beachten.

## Hinweise für KI-Agenten

- API-Basisadresse: `https://api.eventwerk.eu/api/v1`
- OpenAPI 3.1: `https://api.eventwerk.eu/openapi.json` und `/api/v1/openapi.json`. Daraus lassen sich Clients und Typprüfungen generieren.
- Anmeldung: `Authorization: Bearer ew_...`
- Schlüssel: Einstellungen unter `/dashboard/einstellungen`, nur mit Eventwerk Plus und nur für Eigentümer. Der volle Schlüssel wird nur einmal angezeigt. Name und Zeitpunkt der letzten Nutzung werden geführt und ausgegeben.
- Zeiten: Alle Zeitpunkte kommen in UTC mit Suffix `Z`. Die Zeitzone des Events steht getrennt in `timezone` als IANA-Name, Standard `Europe/Vienna`. Clients rechnen selbst um.
- Paginierung: Die Event- und Anmeldelisten liefern `{items, has_more, next_cursor}` mit `limit` (Standard 50, höchstens 200), `cursor` und `updated_since`.
- Grenzen: 200 Anfragen pro Minute je Schlüssel. Der Zähler liegt im Speicher je Instanz, ist hinter mehreren Instanzen ein Vielfaches und beginnt nach einem Deploy neu. Bei Überschreitung antwortet die API mit 429, `rate_limited` und `Retry-After`.
- Gastgrenzen: Anmelde-Link 20 je Stunde je IP-Adresse, Anmeldung 60 je Stunde je IP-Adresse und 3 je Stunde je E-Mail-Adresse und Event.
- Fehler: JSON mit `code` und `message`, optional mit `details`.

Nachrichten gehen per E-Mail an eine Gruppe von Anmeldungen eines Events. Sie können sofort versendet oder für einen Zeitpunkt in der Zukunft geplant werden.

## Empfängerkreise

| Zielgruppe | Empfänger |
| --- | --- |
| all | Offene und bestätigte Anmeldungen. Die Warteliste ist nicht enthalten. |
| confirmed | Nur bestätigte Anmeldungen. |
| waitlisted | Nur Anmeldungen auf der Warteliste. |
| checked_in | Nur bestätigte Anmeldungen, die bereits eingecheckt sind. |

Stornierte und abgelehnte Anmeldungen erhalten nie eine Nachricht. Doppelte E-Mail-Adressen werden entfernt.

## Inhalt

- Betreff mit höchstens 200 Zeichen.
- Text mit höchstens 20.000 Zeichen.
- Zielgruppe, standardmäßig all.
- Optional ein Versandzeitpunkt als RFC-3339-Zeitpunkt in der Zukunft.

## Entwurf, Planung und Versand

1. Nachricht als Entwurf anlegen und prüfen.
2. Entweder sofort senden oder einen Versandzeitpunkt setzen.
3. Eine geplante Nachricht lässt sich abbrechen, solange sie noch nicht versendet wird.
4. Nach dem Versand sind Änderungen und Löschen nicht mehr möglich.

Der Versand läuft im Hintergrund. Die API antwortet auf einen Sofortversand mit Status 202, `status: sending` und der Zahl der Empfänger. Der Status wechselt danach auf sent. Gesendete Nachrichten zeigen zusätzlich die Zahl der fehlgeschlagenen Zustellungen.

> **Hinweis:** Eine Nachricht mit gesetztem Versandzeitpunkt bleibt technisch ein Entwurf. In der Oberfläche erscheint sie als Geplant.

## Versandkontingent

Das Kontingent zählt Empfänger, nicht Nachrichten. Es umfasst alle Empfänger von Nachrichten der Organisation in den letzten sieben Tagen. Eventwerk erlaubt 500 Empfänger pro Woche, Eventwerk Plus 5.000.

Ist das Kontingent erreicht, antwortet der Versand mit Status 403 und dem Code `weekly_send_limit`. Die Antwort enthält unter `details` die Werte `limit`, `used` und `plan`.

## Zustellung über Werkmail

Eventwerk versendet alle E-Mails über die Premium-Infrastruktur von Werkmail (werkmail.eu).

Mehr zur Infrastruktur steht unter [werkmail.eu](https://werkmail.eu).

> **Warnung:** Automatische Erinnerungen vor dem Event sind gebaut und stehen unter Erinnerungen bereit. SMS, Push und WhatsApp sind als weitere Kanäle geplant, aber noch nicht gebaut. Nachrichten werden derzeit nur manuell oder zu einem festen Zeitpunkt versendet.