How personalization parameters work in dynamic email images

If you've ever looked at the HTML behind a personalized email image, you've probably seen something like this in the image address: a question mark, then a string of names and values. That string is where the personalization lives. Understanding it makes dynamic images much less mysterious, and much easier to fix when something goes wrong.

This is a plain-English reference for how personalization parameters work in dynamic email images: what they are, how values get into them, and the rules that keep them working. The examples use Alterable, but the principles apply to any open-time image service.

What a parameter is

A web address can carry extra information after a question mark. Each piece is a parameter, written as a name, an equals sign, and a value. Multiple parameters are joined with an ampersand.

...image.png?firstname=Sarah&points=2340&city=Denver

When an email client requests that address, the image service reads the parameters and uses them to draw the picture. Sarah sees her name, her 2,340 points, and something about Denver.

Where values come from

Nobody types Sarah's name into the address. Your email platform does it, using merge tags. In your email, the address contains a merge tag instead of a value:

...image.png?firstname=*|FNAME|*

When the campaign is sent, the platform replaces the merge tag with each subscriber's own value. Every subscriber's email ends up with a slightly different image address. The image service then does the rest when each email is opened.

Parameter names must match the design

In Alterable, you define variables when you design an image, like firstname, points, or city. The parameter names in the address must match those variable names exactly. Alterable's embed code already includes the right names, with a placeholder where each merge tag goes, so you only need to swap in your platform's tags.

Common parameter types

Personal text values

Names, cities, tiers, codes, product names. These are drawn into the image as text, using the fonts and styles in your design.

Numbers

Points balances, reward amounts, order counts. Pass them as plain numbers without currency symbols or thousands separators unless your design expects them.

Dates and deadlines

For countdown timers that count to a per-contact date, the deadline is passed as a parameter. Full timestamps with timezone information, like 2026-10-01T18:00:00Z, are the safest format. Some platforms store date fields without times, so a plain text field holding the full timestamp can be more reliable.

Subscriber identifiers

Some content needs to recognize the same subscriber across opens, like an evergreen timer that has to remember when someone first opened. For that, the address carries a unique ID from your email platform, often as a uid parameter. Use your platform's generated ID rather than an email address, so no personal data sits in the image URL.

Location

For maps and location-based content, you can pass a city or postal code you already store. That's more reliable than detecting location when the email is opened, since Gmail and Apple Mail load images through their own servers, which can hide where a reader is.

Rules that keep parameters working

Encode values

Spaces, accents, apostrophes, and ampersands can break a web address. Values need to be URL-encoded, which converts special characters into safe codes. Many platforms offer a way to do this. In Mailchimp it's the URL: modifier, as in *|URL:FNAME|*; Klaviyo has a urlencode filter.

Always provide defaults

Subscribers with missing data will send an empty parameter. Set a default in your merge tag where the platform allows it, and a fallback value for each variable in the Alterable design. Then an empty name becomes "there," or disappears from the design gracefully.

Match capitalization

Merge tags are often case sensitive. A field called City won't answer to city, and the failure is silent: the parameter arrives empty and the default appears.

Use the right block

Most email editors only process merge tags inside a web address when it's in an HTML or code block. Standard image blocks usually expect a fixed file and won't fill in tags.

Troubleshooting

If every subscriber sees the default, the merge tag isn't filling in. Check the tag's exact name and capitalization, and confirm the embed is in an HTML block.

If the image is broken only in test emails, it's probably fine. Many platforms don't fill contact-specific merge tags in test sends. Preview with real contacts instead.

If some names break the image, look for special characters and add URL encoding.

If a timer shows the wrong deadline, check the date format and timezone in the field you're passing.

Where to find platform specifics

Each email platform has its own merge tag syntax and quirks. Alterable publishes step-by-step guides for Klaviyo, Mailchimp, HubSpot, Brevo, Constant Contact, Kit, ActiveCampaign, and more, with the exact tags for each.

Once you understand parameters, every type of dynamic content works the same way: personalized images, countdown timers, product blocks, maps, surveys, and scratch cards. Build one on Alterable's free plan at alterable.com and look at the address it produces. The whole system is right there in one line.