Merge Tags
Insert dynamic personalization tokens into text content that get replaced with real values at send time.
function MergeTagEditor() {
const editorRef = useRef<DragbleEditorRef>(null);
return (
<DragbleEditor
ref={editorRef}
editorKey="db_your_key"
editorMode="email"
options={{
mergeTags: {
sort: true,
customMergeTags: [
{
label: "First Name",
value: "{{first_name}}",
category: "Contact",
},
{ label: "Last Name", value: "{{last_name}}", category: "Contact" },
{ label: "Email", value: "{{email}}", category: "Contact" },
{
label: "Company",
value: "{{company}}",
category: "Organization",
},
{
label: "Unsubscribe URL",
value: "{{unsubscribe_url}}",
category: "Links",
},
],
},
}}
/>
);
}
<template>
<DragbleEditor
ref="editorRef"
editor-key="db_your_key"
editor-mode="email"
:options="editorOptions"
/>
</template>
<script setup lang="ts">
const editorRef = ref<InstanceType<typeof DragbleEditor>>();
const editorOptions = {
mergeTags: {
sort: true,
customMergeTags: [
{ label: "First Name", value: "{{first_name}}", category: "Contact" },
{ label: "Last Name", value: "{{last_name}}", category: "Contact" },
{ label: "Company", value: "{{company}}", category: "Organization" },
],
},
};
</script>
@Component({
selector: "app-merge-tag-editor",
standalone: true,
imports: [DragbleEditorComponent],
template: `
<dragble-editor
#editor
editorKey="db_your_key"
editorMode="email"
[options]="editorOptions"
></dragble-editor>
`,
})
export class MergeTagEditorComponent {
@ViewChild("editor") editorComp!: DragbleEditorComponent;
editorOptions = {
mergeTags: {
sort: true,
customMergeTags: [
{ label: "First Name", value: "{{first_name}}", category: "Contact" },
{ label: "Last Name", value: "{{last_name}}", category: "Contact" },
{ label: "Company", value: "{{company}}", category: "Organization" },
],
},
};
}
dragble.init({
containerId: "editor-container",
editorKey: "db_your_key",
editorMode: "email",
options: {
mergeTags: {
sort: true,
customMergeTags: [
{ label: "First Name", value: "{{first_name}}", category: "Contact" },
{ label: "Last Name", value: "{{last_name}}", category: "Contact" },
{ label: "Company", value: "{{company}}", category: "Organization" },
{
label: "Unsubscribe URL",
value: "{{unsubscribe_url}}",
category: "Links",
},
],
},
},
});
Users can insert merge tags using the merge tag button in the text toolbar.
Exclude default merge tags
Set excludeDefaults: true to remove all built-in merge tags and only show your custom tags:
mergeTags: {
excludeDefaults: true,
customMergeTags: [
{ label: 'First Name', value: '{{first_name}}', category: 'Contact' },
{ label: 'Coupon Code', value: '{{coupon_code}}', category: 'Promo' },
],
}
Update merge tags at runtime
Call setMergeTags() to replace the tag configuration without reinitializing the editor:
// React
editorRef.current?.editor?.setMergeTags({
customMergeTags: [
{ label: "First Name", value: "{{first_name}}", category: "Contact" },
{ label: "Coupon Code", value: "{{coupon_code}}", category: "Promo" },
],
});
// Vanilla JS
dragble.setMergeTags({
customMergeTags: [
{ label: "First Name", value: "{{first_name}}", category: "Contact" },
{ label: "Coupon Code", value: "{{coupon_code}}", category: "Promo" },
],
});
Merge tags also work inside link URLs. Users can insert {{unsubscribe_url}} as a button or link href from the link editor. They can also be used in dynamic image URLs to personalize images per recipient.
Merge tag groups
Tags are organized into collapsible groups in the dropdown using the category property. Tags with the same category are displayed together:
const customMergeTags = [
{ label: "First Name", value: "{{first_name}}", category: "Contact" },
{ label: "Last Name", value: "{{last_name}}", category: "Contact" },
{ label: "Company", value: "{{company}}", category: "Organization" },
{ label: "Plan Name", value: "{{plan_name}}", category: "Billing" },
{ label: "Amount Due", value: "{{amount_due}}", category: "Billing" },
];
You can also use nested MergeTagGroup objects for hierarchical grouping:
const customMergeTags = [
{
name: "Contact",
mergeTags: [
{ label: "First Name", value: "{{first_name}}" },
{ label: "Last Name", value: "{{last_name}}" },
],
},
{
name: "Billing",
mergeTags: [
{ label: "Plan Name", value: "{{plan_name}}" },
{ label: "Amount Due", value: "{{amount_due}}" },
],
},
];
Configuration reference
| Property | Type | Default | Description |
|---|---|---|---|
excludeDefaults | boolean | false | Hide built-in default merge tags |
sort | boolean | false | Sort tags alphabetically within groups |
customMergeTags | (MergeTag | MergeTagGroup)[] | [] | Custom merge tags to add |
Method reference
| Method | Returns | Description |
|---|---|---|
setMergeTags(config) | void | Replace the merge tags configuration at runtime |
getMergeTags() | Promise<(MergeTag | MergeTagGroup)[]> | Get the current merge tags list |
Next steps
- Dynamic Images -- personalize images using merge tags in URLs
- Special Links -- add custom link types like unsubscribe
- Display Conditions -- show/hide rows based on merge tag values
- Custom Tools -- build tools that use merge tags in their renderer