Test-E-Mails

Plan Feature

Diese Funktion ist nur in den Plänen Launch, Growth und Scale verfügbar.

Mit Test-E-Mails können Ihre Benutzer eine Vorschau ihrer Vorlage an ein echtes Postfach senden, bevor sie live geht. Wenn die Funktion aktiviert ist, zeigt die Editor-Toolbar eine Test-E-Mail senden-Schaltfläche an.

Funktionsweise

1. Ihr Token-Endpunkt gibt eine Liste erlaubter Empfängeradressen und eine kryptografische Signatur zurück (siehe Einrichtung)
2. Das SDK zeigt eine Test-E-Mail senden-Schaltfläche in der Editor-Toolbar
3. Der Benutzer wählt einen Empfänger aus der erlaubten Liste und klickt auf Senden
4. Das SDK speichert die Vorlage, exportiert das HTML, führt den onBeforeTestEmail-Callback aus (falls konfiguriert) und sendet die E-Mail

Die erlaubte Empfängerliste ist mit HMAC-SHA256 signiert, sodass sie auf der Client-Seite nicht manipuliert werden kann.

Einrichtung

1. Signaturschlüssel abrufen

Den E-Mail-Signaturschlüssel finden Sie in Ihren Projekteinstellungen im Templatical-Dashboard. Dieser Schlüssel wird zum Signieren der erlaubten Empfängerliste verwendet. Speichern Sie ihn sicher auf Ihrem Backend zusammen mit Ihrer Client ID und Ihrem Client Secret.

2. Token-Endpunkt aktualisieren

Ihr Token-Endpunkt gibt bereits eine Token-Antwort zurück (siehe Authentifizierung). Um Test-E-Mails zu aktivieren, fügen Sie der Antwort ein test_email-Objekt hinzu:

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_at": 1709251200,
  "project_id": "proj_abc123",
  "tenant": "acme-corp",
  "test_email": {
    "allowed_emails": ["test@example.com", "team@example.com"],
    "signature": "a1b2c3d4..."
  }
}

Feld	Typ	Beschreibung
test_email	object	Test-E-Mail-Konfiguration (weglassen, um die Schaltfläche auszublenden)
test_email.allowed_emails	string[]	E-Mail-Adressen, die Test-E-Mails empfangen dürfen
test_email.signature	string	HMAC-SHA256-Signatur der erlaubten E-Mail-Liste

Wenn das test_email-Feld fehlt, wird die Test-E-Mail-Schaltfläche in der Toolbar nicht angezeigt.

Signatur berechnen

Der Signaturalgorithmus ist:

1. E-Mail-Adressen alphabetisch sortieren
2. Das sortierte Array JSON-kodieren
3. Den JSON-String mit Ihrem Signaturschlüssel per HMAC-SHA256 signieren

Backend-Beispiele

import crypto from 'crypto';

app.post('/api/token', async (req, res) => {
  // 1. Token von Templatical abrufen
  const response = await fetch('https://templatical.com/api/v1/auth/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      client_id: process.env.TEMPLATICAL_CLIENT_ID,
      client_secret: process.env.TEMPLATICAL_CLIENT_SECRET,
      tenant: req.user.organizationId,
    }),
  });

  const tokenData = await response.json();

  // 2. Erlaubte Test-E-Mail-Empfänger definieren
  const allowedEmails = ['test@your-app.com', 'qa@your-app.com'];

  // 3. HMAC-Signatur berechnen
  const sorted = [...allowedEmails].sort();
  const signature = crypto
    .createHmac('sha256', process.env.TEMPLATICAL_SIGNING_KEY)
    .update(JSON.stringify(sorted))
    .digest('hex');

  // 4. Token + Test-E-Mail-Konfiguration zurückgeben
  res.json({
    ...tokenData,
    test_email: {
      allowed_emails: allowedEmails,
      signature,
    },
  });
});

TIP

Sie können die erlaubten Empfänger dynamisch basierend auf dem authentifizierten Benutzer bestimmen — z. B. nur die eigene E-Mail-Adresse des aktuellen Benutzers oder ein gemeinsames Team-Testpostfach.

onBeforeTestEmail

Wird aufgerufen, bevor eine Test-E-Mail gesendet wird. Verwenden Sie diesen Callback, um das HTML vor dem Versand zu transformieren — z. B. um Merge-Tags durch echte Testdaten zu ersetzen, damit die E-Mail realistisch aussieht.

Der Callback erhält den rohen HTML-String und muss das transformierte HTML zurückgeben (oder ein Promise, das zu diesem aufgelöst wird). Ohne Callback wird das HTML unverändert gesendet.

const editor = await init({
  container: '#email-editor',
  auth: { url: 'https://your-app.com/api/token' },
  onBeforeTestEmail: async (html) => {
    // Testdaten von Ihrer API abrufen
    const testData = await fetch('/api/test-data').then(r => r.json());

    // Globale Regex verwenden, um alle Vorkommen zu ersetzen
    return html
      .replace(/\{\{first_name\}\}/g, testData.firstName)
      .replace(/\{\{last_name\}\}/g, testData.lastName)
      .replace(/\{\{email\}\}/g, testData.email)
      .replace(/\{\{unsubscribe_url\}\}/g, 'https://example.com/unsubscribe');
  },
});

Ratenbegrenzung

Der Test-E-Mail-Versand ist serverseitig ratenbegrenzt, um Missbrauch zu verhindern. Bei Überschreitung des Limits gibt das SDK einen Fehler über den onError-Callback aus.