mailinapp
Documentation menu

„Zum Kalender hinzufügen“-Block

Ein „Zum Kalender hinzufügen“-Block mit einem Tap — und die praktische Lösung für zeitzonenübergreifende Einladungen. Eine versendete E-Mail hat kein JavaScript, um die eigene Zeitzone eines Empfängers zu erkennen, daher kodiert dieser Block Start und Ende des Termins als absoluten Zeitpunkt statt als vorberechnete Ortszeit-Zeichenkette. So zeigt die Kalender-App jedes Teilnehmers den Termin automatisch korrekt in dessen eigener Ortszeit an.

Wie es funktioniert

Der Block ist reiner Inhalt, wie Veranstaltungsort: Es gibt nichts zu beantworten, daher erscheint er nie im Antworten-Dashboard oder CSV-Export. Alle drei Links, die er rendert, nutzen denselben generischen Klick-Tracking-Slot, den jeder einfache linktragende Block verwendet, statt einer eigens dafür gebauten Fähigkeit.

Die Links sind an eine gültige startsAt gebunden: Ein Termin ohne festgelegte Startzeit rendert nur den Titel- und Beschreibungstext, ohne tote Links ins Nichts. Ist startsAt gesetzt, endsAt aber nicht (oder liegt vor startsAt), setzt der Block die Dauer standardmäßig auf eine Stunde nach dem Start — nur „wann es beginnt“ auszufüllen gilt als der häufigste Fall, und jeder nachgelagerte Verbraucher (die .ics-Datei, Google Kalender, Outlook.com) benötigt irgendeinen Endzeitpunkt. location ist ein reines Freitextfeld, das Sie von Hand aus dem Text Ihres Veranstaltungsort- oder Meeting-Link-Blocks ausfüllen; die drei Blöcke sind in dieser ersten Version nicht automatisch verknüpft, also aktualisieren Sie es selbst, wenn sich der Ort ändert.

Aus diesen Angaben rendern drei Links, die sich zu Klick-Tracking-Zwecken eine blockId teilen (die Heatmap bündelt nach Block, nicht nach einzelnem Link, dieselbe Konvention, die auch Social-Links für seine mehreren Icons verwendet):

  • .ics herunterladen — ein signierter Link zu GET /api/calendar, der eine handgeschriebene RFC-5545-Datei (iCalendar) streamt. Es steckt keine npm-Abhängigkeit dahinter — eine .ics-Datei ist reiner Text, gebaut auf dieselbe „von Grund auf“ Weise wie der GIF-Encoder des Countdowns. Die DTSTART/DTEND-Werte der Datei werden als absolute UTC-Zeitpunkte ausgegeben (ein angehängtes „Z“, keine TZID/VTIMEZONE-Komponente nötig) — das ist die eigentliche zeitzonenübergreifende Lösung, nichts zur Renderzeit Berechnetes, sondern schlicht eine Folge davon, dass startsAt/endsAt des Blocks von vornherein als Epoch-Millisekunden gespeichert werden. Die UID des Termins ist ein deterministischer sha256-Hash aus Titel/Beschreibung/Ort/Start/Ende, sodass ein erneutes Herunterladen desselben signierten Links einen einzigen Kalendereintrag aktualisiert statt ein Duplikat zu erstellen. Frei getippter Text wird gemäß RFC 5545 §3.3.11 escaped (Backslashes, Kommas, Semikolons, literale Zeilenumbrüche), und lange Zeilen werden bei der vom Standard geforderten 75-Oktett-Grenze umgebrochen, sodass die lange Beschreibung eines Organisators keine technisch ungültige Datei erzeugen kann. Die URL selbst ist auf dieselbe Weise signiert wie die Endpunkte für Countdown/Formel/Diagramme — die gesamte Termin-Nutzlast wird in die Abfragezeichenfolge serialisiert (kein Firestore-Lesevorgang auf dem GET-Pfad), domänengetrennt von jeder anderen signierten-URL-Familie der App über ein "calendar:"-Präfix im HMAC-Eingabewert, sodass eine für diesen Endpunkt geprägte Signatur niemals gegen einen anderen verifiziert werden kann.
  • Zu Google Kalender hinzufügen — ein einfacher calendar.google.com/calendar/render?action=TEMPLATE&...-Deep-Link, zum Sendezeitpunkt erstellt, ohne serverseitigen Umweg.
  • Zu Outlook.com hinzufügen — ein einfacher outlook.live.com/calendar/0/action/compose?...-Deep-Link, ebenfalls zum Sendezeitpunkt erstellt.

Titel, Beschreibung und Ort werden jeweils vorsorglich auf feste Höchstlängen gekürzt (200 / 2.000 / 300 Zeichen), bevor einer der drei Links gebaut wird, damit ein sehr langes Freitextfeld keinen defekten .ics-Link oder eine überlange Abfragezeichenfolge bei den beiden Web-Links erzeugen kann.

Konfigurierbare Felder:

  • Titel des Termins.
  • Beschreibung (optional).
  • Beginnt am — erforderlich, damit überhaupt Links gerendert werden.
  • Endet am (standardmäßig 1 Stunde nach Beginn).
  • Ort (optional, Freitext).
  • Hintergrundfarbe, Innenabstand, Rahmen und Eckenradius der Karte.
  • Farbe/Größe des Titeltexts sowie gemeinsame Farb-/Hintergrund-Überschreibungen für die drei Links.

Beispiele

Subject

Save the date: our fall meetup

Jedes Projekt mit dem Zweck „Veranstaltung“ startet bereits mit einem Block „Zum Kalender hinzufügen“ neben Meeting-Link, Veranstaltungsort und RSVP — siehe Veranstaltungen & Webinare für das vollständige Muster von der Einladung bis zur Erinnerung, dessen Teil dieser Block ist. Ein Sportverein verwendet denselben Block Woche für Woche für Trainings- und Spielzeiten wieder, sodass der Kalender jeder Familie unabhängig davon, in welcher Zeitzone sie gerade reist, den Zeitplan korrekt widerspiegelt — siehe Sportteams & Vereine. Eine Webinar-Reihe kann diesen Block direkt in eine Bestätigungs-E-Mail einfügen, die unmittelbar nach der Anmeldung versendet wird, sodass der Empfänger den Termin im selben Moment zu seinem Kalender hinzufügt, in dem er sich angemeldet hat, statt sich später darauf zu verlassen, dass er sich erinnert.

So sieht der statische Fallback aus

<div style="margin:12px 0;background-color:transparent">
  <p style="margin:0 0 8px;font-weight:600;font-size:16px;color:#111827">Q3 Product Launch</p>
  <a href="https://mailinapp.com/api/calendar?d=eyJ0aXRsZSI6...&s=abc123..."
     style="display:inline-block;padding:10px 20px;background-color:#4f46e5;color:#ffffff;
            border-radius:6px;text-decoration:none;font-size:14px;font-weight:600;margin:0 8px 8px 0">
    Download .ics
  </a>
  <a href="https://calendar.google.com/calendar/render?action=TEMPLATE&text=Q3+Product+Launch&dates=20260901T170000Z%2F20260901T180000Z"
     style="display:inline-block;padding:10px 20px;background-color:#4f46e5;color:#ffffff;
            border-radius:6px;text-decoration:none;font-size:14px;font-weight:600;margin:0 8px 8px 0">
    Add to Google Calendar
  </a>
</div>

Dies ist der gesamte versendete Block — drei einfache Links (der dritte, Outlook.com, hier der Kürze halber weggelassen), gebaut aus denselben Termindetails, ohne Bild oder gesperrten Inhalt.

Siehe auch