In This Article:

    Common Merge Fields

    In This Article:

      Overview

      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:

      personalization.png

      And you can insert merge fields into forms:

      personalized_thank_you.png 

      Add Merge Fields to Emails

      Your email blasts as well as your automated email triggers can be built to use merge field data to personalize the subject line or the content.

      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:

      Dear [[First_Name]],

      This would generate an email to someone who has signed up with the first name of Kristen as:

      Dear Kristen,

      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:

      1. The thank you page a supporter lands on after he or she makes a donation
      2. 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

      insert_merge_field_redirect.png

      Copy the public URL

      View the public page...

      view_page.gif

      ... and then copy the public URL

      copy_url.png

      Format the Redirect

      Go to the Follow Up tab of the original form (in this case a donation form)

      follow_up_tab.png

      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.

      add_field_to_URL.png

      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:

      1. Available merge fields differ with different types of Salsa pages
      2. 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.

      -Standard Supporter Fields

      -Custom Fields

      -Donation Pages

      -Storefronts

      -Actions

      -Events

      -Distributed Events

      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.  

      Standard Supporter Fields

      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:

      • [[Title]]
      • [[First_Name]]
      • [[MI]]
      • [[Last_Name]]
      • [[Suffix]]
      • [[Email]] User for signup confirmation messages
      • [[Phone]]
      • [[Cell_Phone]]
      • [[Work_Phone]]
      • [[Street]]
      • [[Street_2]]
      • [[City]]
      • [[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
      • [[Zip]]
      • [[Country]] provides the full text name of the country, e.g., United States or Brazil.
      • [[Organization]]
      • [[Occupation]]
      A list of all supporter fields can be found here.

      Custom Fields

      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.

      api_name.png

      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.

      Donation Pages

      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.

      Storefronts

      • [[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
      • [[address_line]]
      • [[address_line_2]]
      • [[municipality]]
      • [[region]]
      • [[postal_code]]

      Actions

      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:
      action-key-firebug
      Enlarge.
       


      Events

      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:
          • https://BASENODEURL/o/ORGNUMBER/p/salsa/event/common/public/?event_KEY=[[event_KEY]]
        • [[Additional_Attendees]] For events permitting guest registrations, the number of additional guest attendees beyond the main registrant.
      Example: Supporter registers self, and adds as guests a spouse and a child. Additional_Attendees = 2 (not 3).

      Distributed Events

      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
          • https://BASENODEURL/o/ORGNUMBER/p/salsa/event/common/public/?event_KEY=[[event_KEY]]
        • The event's [[Start]] and [[End]] dates
          • [[Event_Name]]
          • [[Description]]
          • [[Address]]
      Was this article helpful?
      0 out of 0 found this helpful
      Have more questions? Submit a request

      Comments

      14 comments
      • where is the link to all the supporter fields?  I know it exists

      • here it is

        https://help.salsalabs.com/entries/21518315-Standard-supporter-fields-the-supporter-object-

        this page should also have links to the standard fields of other tables so we can navigate around related articles.

      • Can I include merge fields for an event, such as the event location's address, date and time, etc.? I don't see that here. It would be nice if I could create a standard event reply email and reuse it for each event rather than having to draft a new one each time.

        Thanks.

      • Hi Nathan,

        This is a feature request in the queue, but unfortunately it's not something that exists at this time.  I've made a note on the feature request that yours is another vote for it to be prioritized.

        Thanks!

      • How do I change the default text that appears if you use a merge field for information that's not in someone's supporter record. For example, right now someone see's "Supporter" if we don't have their first name and we use the [[First_Name]] merge field, but can I change that to say something else? I know there's a way to do this, but I can't find it! Thanks

      • Hi Julia,

        To change the default merge fields follow these instructions.

        Cheers!

      • What are the field names for in honor of name and in memory of name in case one wanted to use them on the email trigger response?  I can not find a list of donation fields.  Barbara Hohlt

      • Hi Barbara,

        The donation object documentation is here for your reference.  The specific fields you requested are:

        • [[In_Memory_Name]]
        • [[In_Honor_Name]]

        Remember, these donation merge fields can only be used in email autoresponses.  Streaming emails can only pull in merge fields from the supporter table.

        Best,

        Rebecca

      • I've tried to get merge fields to reference groups and failed.  I'd like an auto alert to tell me if a supporter clicked a checkbox for a group on a donation page.  

      • Hi Meghan,

        Unfortunately, merge fields for group names are not possible at this time. There's an open feature request for this - I'll add your voice to it so that updated comments can be reviewed during product roadmap triage.

      • Why does the Publishing Tool say this?

        This email cannot be converted to use statistics because :

        • Merge field amount is not supported
        • Merge field amount is not supported

        I'm creating an autoresponder page to thank donors, and I want it to say the amount they just gave.

      • Is there a way to auto-generate the name of the page or fund the person donated to into the autoresponse? I ask because we would like to keep the number of autoresponses we have down to a manageable number, but we also want people to know/remember the fund the actually contributed to, and not just have a generic "Thank you for your donation of XX."

      • When a person does not have a first name entered into the data base, can I enter a bit of code to replace the blank with "friend?"

         

      • Is there a way to merge target fields into actions? E.g., "Dear Senator [[Target_last_name]]" ?

      Please sign in to leave a comment.