Merge-Tags

Merge-Tags sind Platzhaltervariablen in Ihren E-Mail-Vorlagen, die beim Versand durch echte Daten ersetzt werden. Zum Beispiel könnte {{first_name}} für einen Empfänger zu „Jana" und für einen anderen zu „Alex" werden.

Das Templatical SDK erkennt Merge-Tags im Vorlageninhalt und zeigt sie als benutzerfreundliche Bezeichnungen im Editor an, sodass Ihre Benutzer „Vorname" statt der rohen {{first_name}}-Syntax sehen.

Konfiguration

Übergeben Sie Merge-Tags über die Option mergeTags in init():

const editor = await init({
  container: '#email-editor',
  auth: { url: 'https://your-app.com/api/token' },
  mergeTags: {
    tags: [
      { label: 'Vorname', value: '{{first_name}}' },
      { label: 'Nachname', value: '{{last_name}}' },
      { label: 'E-Mail', value: '{{email}}' },
      { label: 'Abmelde-URL', value: '{{unsubscribe_url}}' },
    ],
  },
});

Jeder Tag hat:

Eigenschaft	Typ	Beschreibung
label	string	Anzeigename im Editor
value	string	Der Merge-Tag-String zum Abgleich im Vorlageninhalt

Unterstützte Syntaxen

Verschiedene E-Mail-Plattformen verwenden unterschiedliche Merge-Tag-Syntax. Das SDK unterstützt 5 integrierte Presets und benutzerdefinierte Muster.

Integrierte Presets

Preset	Wert-Tags	Logik-Tags	Plattformen
liquid (Standard)	{{variable}}	{% if %} ... {% endif %}	Liquid, Jekyll, Shopify, Twig
handlebars	{{variable}} oder {{{variable}}}	{{#if}} ... {{/if}}	Handlebars, Mustache, Ember
mailchimp	*|VARIABLE|*	*|IF:CONDITION|* ... *|END:IF|*	Mailchimp, Mandrill
ampscript	%%=variable=%%	%%[IF ...]%% ... %%[ENDIF]%%	Salesforce Marketing Cloud
django	{{variable}}	{% if %} ... {% endif %}	Django, Jinja2

Preset verwenden

mergeTags: {
  syntax: 'mailchimp',
  tags: [
    { label: 'Vorname', value: '*|FNAME|*' },
    { label: 'Nachname', value: '*|LNAME|*' },
    { label: 'E-Mail', value: '*|EMAIL|*' },
  ],
},

Benutzerdefinierte Syntax

Wenn Ihre Plattform eine Syntax verwendet, die nicht von den Presets abgedeckt wird, übergeben Sie ein benutzerdefiniertes Objekt mit value- und logic-Regex-Mustern:

mergeTags: {
  syntax: {
    value: /\$\{.+?\}/g,       // Erkennt ${variable}
    logic: /\$\{#(\w+).*?\}/g, // Erkennt ${#if ...}
  },
  tags: [
    { label: 'Vorname', value: '${first_name}' },
    { label: 'Firma', value: '${company}' },
  ],
},

Eigenschaft	Typ	Beschreibung

| value | RegExp | Muster zur Erkennung von Wert-Merge-Tags (z. B. {{name}}) | | logic | RegExp | Muster zur Erkennung von Logik-Merge-Tags — Gruppe 1 muss das Schlüsselwort erfassen (z. B. if, endif) |

Beide Muster müssen das globale Flag (/g) verwenden.

Darstellung von Merge-Tags im Editor

Wert-Tags

Wenn ein konfigurierter Merge-Tag-value im Vorlageninhalt gefunden wird, ersetzt der Editor die rohe Syntax durch ein gestyltes Chip mit dem label. Zum Beispiel erscheint {{first_name}} als beschriftetes Badge mit „Vorname".

Logik-Tags

Logik-Tags (Bedingungen wie {% if %} oder {{#if}}) erscheinen als Schlüsselwort-Badges, die das erkannte Schlüsselwort anzeigen (z. B. „if", „endif", „else"). Diese werden über das syntax.logic-Muster erkannt.

Dynamische Merge-Tag-Auswahl

Für Anwendungen mit vielen oder dynamischen Merge-Tags verwenden Sie den Callback onRequestMergeTag anstelle von (oder zusätzlich zu) einer statischen tags-Liste. Damit können Sie Ihre eigene Auswahl-Oberfläche anzeigen:

const editor = await init({
  container: '#email-editor',
  auth: { url: 'https://your-app.com/api/token' },
  mergeTags: {
    syntax: 'liquid',
    tags: [], // Kann leer sein bei Verwendung der dynamischen Auswahl
  },
  onRequestMergeTag: async () => {
    // Eigene Merge-Tag-Auswahl anzeigen (Modal, Dropdown usw.)
    const selected = await showMergeTagPicker();

    if (!selected) {
      return null; // Benutzer hat abgebrochen
    }

    return {
      label: selected.name,     // z. B. "Vorname"
      value: selected.mergeTag, // z. B. "{{first_name}}"
    };
  },
});

Der Callback wird ausgelöst, wenn der Benutzer auf die Merge-Tag-Schaltfläche in der Text-Toolbar klickt. Er muss ein MergeTag-Objekt ({ label, value }) oder null zurückgeben, wenn der Benutzer abbricht.

Anwendungsfälle

• Personalisierung — Empfänger mit Namen begrüßen, auf deren Unternehmen verweisen oder kontospezifische Details einfügen
• Dynamische URLs — Eindeutige Links wie Abmelde-URLs, Profilseiten oder Tracking-Links einfügen
• Bedingte Begrüßungen — Logik-Tags verwenden, um unterschiedliche Inhalte basierend auf Empfängerdaten anzuzeigen (siehe auch Anzeigebedingungen)
• E-Commerce — Bestelldetails, Produktempfehlungen oder Treueprogramm-Status einfügen

Best Practices

• Beschreibende Labels verwenden — „Kunden-Vorname" ist klarer als „fname" für Ihre Benutzer
• Syntax der Versandplattform abgleichen — Wählen Sie das Preset, das zu Ihrem E-Mail-Versanddienst passt (z. B. 'mailchimp' für Mailchimp)
• Alle häufig verwendeten Tags einbeziehen — Je mehr Tags Sie konfigurieren, desto besser die Editor-Erfahrung
• Dynamische Auswahl für große Tag-Listen — Wenn Sie Dutzende von Merge-Tags haben, verwenden Sie onRequestMergeTag mit einem durchsuchbaren Modal anstelle einer langen statischen Liste