Skip to main content

​
What are Merge Tags?

Merge tags are placeholders in your cards that get replaced with dynamic, personalized content when the card is sent. They allow you to create one card template that can be customized for each recipient with their specific information.

​
How Merge Tags Work

When you send a card via API:
  1. Template: Your card contains merge tag placeholders like {{name}}
  2. Data: You provide the actual values in your API request
  3. Processing: CardClan replaces placeholders with real data
  4. Result: Recipient gets a personalized card

​
Merge Tag Syntax

Merge tags use double curly braces syntax:
Examples:
  • {{name}} → “John Doe”
  • {{company}} → “Acme Corporation”
  • {{email}} → “john@example.com”

​
Standard Merge Tags

CardClan supports these commonly used merge tags:
  • {{ name }} - Full name - {{ email }} - Email address
  • Any custom field name you define - Examples: {{ productName }}, {{ accountManager }}, {{ eventDate }}

​
Using Merge Tags in API Requests

When sending a card, provide merge tag values in the mergeTags array:
The mergeTags parameter expects an array, but typically contains a single object with the recipient’s data.

​
Image Merge Tags

Merge tags can also swap images, not just text. You can give each recipient their own company logo, headshot or personalized screenshot. You place an image on the card as usual, then bind it to a merge tag. Each recipient’s value for that tag is an image URL. When they open the card, the image you placed is replaced with the image at their URL.

​
Bind an image to a merge tag

1

Select an image on an inner page

In the card editor, click an image on any page after the cover, or on a dynamic cover. To personalize a page’s background image instead, open that page’s Background panel.
2

Turn on Replace with merge tag

In the image panel on the right, switch on Replace with merge tag.
3

Pick or create a tag

Choose an existing merge tag from the dropdown, or choose + New tag to create one. Image tags share the tag list with text tags, so the same naming rules apply: letters, numbers and underscores.
In the editor, a bound image shows a small {{tagName}} badge so you can see which images are dynamic. To unbind an image, switch Replace with merge tag off.

​
Provide image URLs for recipients

An image tag’s value is an https image URL. You supply it the same way as any other merge tag:
  • CSV upload: map a column of image URLs to the tag (how to upload a CSV)
  • Zapier and Pabbly Connect: map a field that holds the image URL to the tag
  • API: pass the URL as the tag’s value in mergeTags
  • AI assistants (MCP): give the URL to your assistant, which passes it to send_card (MCP guide)
API example

​
How the recipient’s image is shown

  • Same spot, same size. The recipient’s image takes the position, size and rotation of the image you placed.
  • Cropped to fit. The image fills the original box and keeps its proportions. Any overflow is cropped evenly from the edges, and the image is never stretched. Square logos and headshots work best in a square box.
  • Always a fallback. If the value is empty, isn’t a valid https URL, or the image fails to load, the recipient sees the image you placed. They never see a broken image.
A static cover (the default) and its image in the email are the same for every recipient. To personalize the cover and the email image too, switch the card to a dynamic cover.
Use a public https link that points straight at the image file (for example a .png or .jpg), not at a web page that contains the image. Links that need a login, have expired, or point to files over 10 MB won’t load, and the recipient sees your fallback image instead.

​
Next Steps

Now that you have learned about merge tags:
  1. Explore examples
  2. Explore the API reference for detailed endpoint documentation