When to use it
Merge Fields are commonly used to personalize content on forms and in email blasts. You can use merge fields on all Salsa forms and emails to improve your email metrics (opens, click-throughs, and conversions).
You can insert merge fields into email blasts:
And you can insert merge fields into forms:
Add Merge Fields to Emails
Just insert one or more Salsa merge fields into a trigger's subject, html content, and/or text content using the syntax [[merge_field]] where you would intend to place its corresponding content.
For instance, an email that uses the [[First_Name]] merge field might begin:
This would generate an email to someone who has signed up with the first name of Kristen as:
Add Merge Fields to Redirect Forms
Redirect Forms are the forms supporters are redirected to after they complete an action on an initial form. A few examples:
- The thank you page a supporter lands on after he or she makes a donation
- The tell a friend page a supporter lands on after he or she signs an online petition
Personalize the content on these redirect forms following these steps:
Add merge fields to the redirect form
Copy the public URL
View the public page...
... and then copy the public URL
Format the Redirect
Go to the Follow Up tab of the original form (in this case a donation form)
Paste the URL (copied above) in the Redirect to field.
Manually append the syntax and any merge fields onto the end of the URL you've pasted.
Find All Available Merge Fields
You can insert merge fields into subject lines and forms, but first you have to know what the merge fields are. There is no single, comprehensive list of all merge fields available for both of the following reasons:
- Available merge fields differ with different types of Salsa pages
- Custom fields vary by Salsa account
To find the merge fields on any given page, set up an Email Autoresponse and click the Append Available Values checkbox on the Advanced Options tab. Add the autoresponse to the page in question (i.e. the donation page or the online petition) and follow the instructions in the Autoresponses documentation to send yourself an email with all of the merge fields available on that page.
Common Merge Fields
To save you the step of identifying all potential merge fields on a form (see above), the following is a list the most frequently used merge fields. They are case-sensitive.
If you use the common merge field [[First_Name]] and the First Name field in a supporter record is blank, what should display to that supporter? Should the form or email blast say Dear Supporter? Should it say Dear Friend? You can customize this content by updating default merge values.
Salsa's standard supporter fields are usually the capitalized word or phrase exactly as it appears (with underscores for spaces) in your Salsa headquarters or on an end-user form. So, [[City]] for City, and [[First_Name]] for First Name.
Here are the most frequently used Salsa supporter fields:
- [[Email]] User for signup confirmation messages
- [[State]] provides the standard two-letter postal abbreviation for American states and Canadian provinces, e.g., CA rather than California
- [[StateName]] provides the full state name of a supporter's address, e.g. Texas rather than TX
- [[Country]] provides the full text name of the country, e.g., United States or Brazil.
Custom fields will use the same double-bracket syntax as regular supporter fields; the field name within those brackets will be the API Name you assign to your custom field.
If you're not sure of the API Name for one of your custom fields, go to the Supporter Package and click on Manage Custom Fields. From there, click on the edit link of the custom field in question to find the API Name as shown above.
These fields will generally return the database value of the user's response. For instance, a merge field [[religion]] on a custom field which is configured as a VARCHAR field -- a single line of text the user can enter -- might return Anglican if that's what the user types in. However, if it's configured as a RADIO field -- where you provide the user a limited picklist of options -- and "Anglican" is associated with a response whose database value is 1, then 1 will be provided by the merge field.
In addition to the regular supporter fields, donation pages generate a variety of donation-specific merge fields useful for donor receipts.
- [[amount]] The total amount of the gift or transaction
- [[Transaction_Date]] The date and time when the donation was processed.
- [[CURRENT_DATE]] offers a more reader-friendly formatted date (e.g., January 13, 2011 instead of the Salsa format of 2011-01-13 15:42).
- [[PNREF]] A unique alphanumeric code returned by the merchant gateway for each transaction. Handy for use as a "confirmation code" in a reply autoresponse.
- [[RPREF]] A unique alphanumeric code returned by the merchant gateway for a new recurring donation. Handy for use as a "confirmation code" in a reply autoresponse.
- [[donation_KEY]] Returns the numeric donation KEY value associated with the donation in Salsa; can be used as a transaction ID number.
- [[donate_page_KEY]] Returns the primary key for the donation page that was used for this donation.
- [[Credit_Card_Digits]] Returns a securely obfuscated card value such as 4111xxxxxxxx1111 useful for receipts.
- [[Credit_Card_Expiration]] Returns the credit card's expiration in MM/YY format, e.g., 03/12.
- [[Tracking_Code]] The tracking code associated with the gift. Since this will be your own organizational code, it is probably most useful for internal notifications rather than acknowledgments to the donor.
- [[PAYPERIOD]] The frequency of a recurring donation, e.g. monthly, quarterly, annually. Caution: The frequency is returned as a code and not as a useful description. The mapping of codes to payperiods follows.
- WEEK - Weekly
- MONT - Monthly
- QTER - Quarterly (every 3 months)
- YEAR - Yearly
- [[TERM]] The number of times the above pay period will run. E.g. if the pay period is monthly, and the term is 6, then the donor will be charged every month for six months. if [[TERM]] is 9999, then the recurring donation will continue forever or until the credit card expires.
- [[Start_Date]] The starting date of the recurring donation. Subsequent donations will be processed as close as possible to this date (depending on the pay period chosen).
- [[recurring]] A flag indicating whether or not the donation was recurring. If the value is one then the donation was a recurring donation. Otherwise the value is zero.
- [[recurring_donation_KEY]] the database key for a recurring donation. If [[recurring]] is one, then this is a recurring donation database key. if [[recurring]] is zero, then the value is -1.
- [[Order_Info]] A human-readable text itemization of the entire order, very useful both for purchaser receipts and for internal fulfillment notices
- [[name]] Shipping Name
Actions can generate fields for the subject line and content of the message launched by the action. These merge fields have names that are specific to each set of content, so if you want to include the text of the action message sent in an acknowledgment email, that acknowledgment will need to be specific to one and only one action page.
- [[Content1111]] Provides the body of the action message (but not the subject) sent by the user, where 1111 is the key number of the specific content the user is sending.
- [[Subject1111]] Provides the subject of the action message (but not the body) sent by the user, where 1111 is the key number of the specific content the user is sending.
The key number will not be the key number for the action itself. To find the key number of the subject and content section, use Firebug or another similar web development tool on the active public facing page. When you do so, you should see something like what you see here:
Free RSVP events generate the regular supporter registration fields.
Events with paid tickets place their transactions on Salsa's Donation table, and those transactions generate all the same donations merge fields, such as [[amount]] and [[PNREF]].
In addition, all events (both paid and unpaid) have these merge fields available:
- [[event_KEY]]The unique key number of the event registered for. This can be used to include a link back to the event as a reference for the registrant -- especially if the same trigger will be used for multiple different events. Use this format:
- [[Additional_Attendees]] For events permitting guest registrations, the number of additional guest attendees beyond the main registrant.
A distributed event's create-an-event page generates merge fields for each unique event your supporters create through it. These fields can be used to customize an acknowledgment email that includes event details.
- [[event_KEY]]The unique key number of each event created through the distributed event page. This can be used to send your event host a link to her or his event
- The event's [[Start]] and [[End]] dates