Merge Field
A merge field is a placeholder that Salesforce replaces with real record data when a template, formula, or page is processed.
Definition
A merge field is a placeholder that Salesforce replaces with real record data when a template, formula, or page is processed. You write the placeholder once, and the platform swaps in the live value at the moment the surface runs. A classic example is {!Contact.FirstName} in an email, which becomes Maria or David depending on who receives the message.
The merge field is how personalization works across nearly every template-driven feature in Salesforce. Email templates, formula fields, validation rules, Visualforce pages, approval emails, and letterheads all read field values through merge fields. Almost every standard and custom field is available as one. The exact wrapper changes by surface, but the idea stays the same: name a field, and Salesforce fills it in.
How merge fields resolve across each Salesforce surface
The syntax: curly braces, an exclamation point, and a field name
The most common merge field wrapper is a pair of curly braces with an exclamation point: {!FieldName}. Inside the braces you put the field API name, optionally prefixed with the object. {!Account.Name} pulls the account name. {!Opportunity.Amount} pulls the amount. {!User.Email} pulls the running user email. When Salesforce renders the surface, it finds each {! ... } token and substitutes the matching value from the record in context. The wrapper is not universal. Email templates come in two flavors. Templates that use single braces or the exclamation form, like {!Contact.Name}, are Salesforce Merge Language, often shortened to SML. Templates that use three braces, like {{{Recipient.FirstName}}}, are HML, the newer HTML markup language used by some Lightning email templates. Formulas and validation rules are different again. There you reference a field directly with no braces at all, writing Account.Name or Amount, because the whole expression is already a formula. The braces matter when a surface mixes field references with plain text or markup. That is why templates and Visualforce need them, and pure formulas do not.
Cross-object references and relationship depth
A merge field can walk a relationship to read a value from a related record. {!Opportunity.Account.Name} starts at the opportunity, hops to its parent account, and returns the account name. {!Case.Contact.Email} reads the email of the contact linked to a case. The dot notation chains lookups and master-detail relationships together, the same way a relationship query traverses parents. This traversal has a ceiling. Salesforce limits cross-object field references to a fixed number of relationship hops from the starting object. Practical templates rarely go more than two or three levels deep, but the limit exists, and a chain that is too long simply will not save. The other constraint is direction. Merge fields and formula references traverse upward to parent records cleanly. Reaching down to child records, like listing every line item on an order, is not something a single merge field can do. That job belongs to related lists in templates or to a query in code. Plan the path before you write it. If the value you want lives three lookups away, confirm every link in the chain is populated, because one empty lookup in the middle breaks the whole reference.
Global merge fields for user, org, and system context
Not every value you want to merge lives on the record. Salesforce exposes global variables that act as merge fields for context that sits outside the current row. These start with a dollar sign. {!$User.FirstName} returns the first name of the person currently running the surface, which is perfect for a signature line. {!$Organization.Name} returns your company name from the org profile. $Profile and $Setup expose information about the running user profile and custom settings. These globals work in formulas, email templates, and Visualforce, and they save you from building an explicit lookup just to greet someone or stamp the org name. A welcome message that opens with Hi {!$User.FirstName} needs no relationship at all, because the running user is always known. Approval processes add their own context-aware merge fields. {!ApprovalRequest.fieldName} and {!Approval_Requesting_User.fieldName} let an approval email reference details of the request and the person who submitted it. Those values shift depending on where the record sits in the approval, so the same template reads differently at each step.
Merge fields inside email templates and letterheads
Email templates are where most people first meet merge fields. In the Lightning email composer or template builder, you click the merge field button to open a picker, choose a field, and Insert drops the correct token into your content. The picker is the safe way in, because it writes the exact API name and the correct wrapper for the template type. Fields about the primary recipient, the lead or contact or person account, are available, alongside fields from related records like Account, Opportunity, Campaign, Case, and User. Field-level security still applies. A field a user cannot see will not merge for them, even if it exists on the record. That is why a template can look complete to an admin and render blank for a sales rep with tighter access. Letterheads and the body share the same merge behavior. The most common surprise is a blank where a value should be. If a merge field has no data, because the field is empty or the relationship is missing, Salesforce renders nothing. The result is awkward output like Dear , with the name simply gone. Designing around that gap is part of building a good template.
Merge fields in formulas, validation rules, and Visualforce
Formula fields and validation rules use field references without braces. A formula field might be Account.Name & " - " & Opportunity.StageName, stitching values into one output. A validation rule might fire when Amount > 100000 && IsClosed = false. In both cases the field name is the merge mechanism, read live whenever the formula evaluates. These references are how a formula reaches a parent record value or a global variable without any extra configuration. Visualforce sits in between. It uses the {! ... } form, so a page can render <apex:outputText value="{!Account.Name}"/> to show the account name. Visualforce expressions go further than a plain field swap. They can call controller methods, evaluate formula functions, and combine values, but the merge field is the foundation they build on. The shared idea across all three is binding. The text you author names a field, and the runtime resolves that name to a value at the moment it processes the surface. Whether the surface is a stored formula, a saved rule, or a rendered page, the substitution happens late, against the record actually in context.
Why merge fields go blank, and how to handle nulls
The single biggest source of merge field trouble is missing data. A merge field that points at an empty field, or a relationship that does not exist for that record, resolves to an empty string in most surfaces. Nothing errors. The output just has a hole in it. A greeting becomes Dear , and a closing becomes a blank line where a name belonged. Formulas give you tools to fill those holes. BLANKVALUE(Contact.FirstName, "there") substitutes a friendly default when the first name is empty, turning Dear , into Dear there. NULLVALUE does the same job for older field types. In email templates, an IF() expression can swap in alternate text when a value is missing, so the message reads cleanly either way. Typos are the other failure mode. A merge field with a misspelled API name does not throw an error you will notice, it simply fails to resolve and leaves a gap or, worse, displays the raw token. Newer Salesforce builders validate merge field syntax when you save, which catches malformed references early. The durable habit is to use the picker, never hand-type API names, and test the finished template against several real records where the data is deliberately incomplete.
Insert merge fields into a Lightning email template
You do not create a merge field as a standalone record. You insert one while building a surface that supports it. Here is how to add merge fields to a Lightning email template so the message personalizes itself per recipient.
- Open the email template builder
In Setup or the App Launcher, go to Email Templates and create or edit a Lightning email template. Set the Related Entity Type so the picker knows which object fields to offer.
- Place your cursor and open the merge field picker
Click in the subject or body where the dynamic value belongs, then click the merge field button in the toolbar to open the picker.
- Choose the field and insert it
Pick the recipient or related field you want, such as Contact First Name or Account Name, then click Insert. The builder writes the correct token, like {!Contact.FirstName}, for you.
- Add a fallback for empty values
For fields that might be blank, wrap the reference so a default shows instead, so a missing first name reads as a friendly word rather than nothing.
- Preview with a real record and save
Use the preview option against an actual record, confirm every token resolves, then save and activate the template.
Sets which object the template targets so the merge field picker lists the right standard and custom fields.
Merge values from the primary recipient, the lead, contact, or person account the email is sent to.
Merge values from associated records like Account, Opportunity, Campaign, or Case linked to the recipient or the Related To record.
Insert {!$User.FirstName} or {!$Organization.Name} to add running-user and company context without a lookup.
- Field-level security still applies, so a field the sender cannot see renders blank for them even though it exists on the record.
- An empty field or missing relationship produces an empty string, not an error, which is how you get output like Dear , with the name gone.
- Cross-object references only reach so many relationship hops, and they traverse to parent records, not down to child records.
- Hand-typed API names fail silently on a typo, so always insert through the picker rather than typing the token yourself.
Prefer this walkthrough as its own page? How to Merge Field in Salesforce, step by step
Trust & references
Cross-checked against the following references.
Straight from the source - Salesforce's reference material on Merge Field.
- Merge Fields for Visualforce PagesSalesforce
- Merge Fields for Classic Approval ProcessesSalesforce
Hands-on resources to go deeper on Merge Field.
About the Author
Dipojjal Chakrabarti is a B2C Solution Architect with 29 Salesforce certifications and over 13 years in the Salesforce ecosystem. He runs salesforcedictionary.com to help admins, developers, architects, and cert/interview candidates sharpen their fundamentals. More about Dipojjal.
Test your knowledge
Q1. Which syntax does a Lightning-era Merge Field use to inject a record value into an email template?
Q2. How can a Merge Field reach a value on a related parent record, such as the account behind an opportunity?
Q3. On which kind of Salesforce surface is a Merge Field resolved into actual record data?
Discussion
Loading discussion…