Skip to content
English
  • There are no suggestions because the search field is empty.

Using merge fields in email templates

How to insert merge fields, which links a template must contain, and what happens when a field has no value.

How to insert merge fields, which links a template must contain, and what happens when a field has no value.

This is for System Admin and HR users who edit templates under Settings, then Automations & Communication, then Communication Templates. You should have a template open in the editor. The full list of fields for each category is in "Merge fields available for each template category".

Insert a merge field

A merge field is a tag in double curly brackets, such as , that Recruit replaces with the real value when the message is sent. You can use them in the subject and the body.

  1. Click into the Subject Line or the Body where you want the field. In the body this works in both the Editor and Raw HTML views.
  2. Below the body, select the Merge fields button.
  3. Search or scroll to the field you want and select it.

The helper text reads "Click a merge field to insert it at the cursor." Recruit inserts the field where your cursor is and keeps your cursor in the box, so you can carry on typing. Where the page is read-only, for example for a shared template, or while the body is still loading, the picker copies the field to your clipboard instead ("Click to copy a merge field to clipboard.") and you paste it yourself. You can also type a field by hand, for example , as long as the spelling matches.

Which fields a template can use

Each category has its own fixed list, because each kind of email is sent with different information. The picker shows only the fields for the category currently selected in the editor. Change the category and the list changes.

If the subject or body contains a field the category cannot fill, Save is refused. One message lists every field that failed, in this form: "{field}: {token} can't be used in {category} templates. Remove it or choose a field from the merge field picker." The message appears at the subject or body box that failed and your cursor moves there. If you change a template's category to one that cannot fill its fields, the same warnings appear before you save. A few older spellings, such as , still work wherever the current spelling works. The picker hides them and shows only the current one.

General Correspondence emails can use job fields such as and , and , only when the email is sent from a job or an application. If an email uses job fields and no job is selected, the composer shows "This email uses job fields" followed by the field names and a reminder to send it from a job or an application, or remove them. Send stays disabled until you do one or the other.

Links in templates

Fields that are links, such as , and , are created separately for each recipient at the moment the email is sent. Preview shows a sample link and tells you which ones will be generated.

A link field typed as plain text in an email body becomes a clickable link when the email is sent. For example, a bare or in the body turns into a link showing the web address. This applies to the body only, never to the subject or to an SMS. A link you have already built yourself, using the Link button in the editor, is left exactly as you wrote it.

Some categories require a link before you can save.

  • Reference Request must include .
  • Application Started must include .
  • Application Form Reminder must include .
  • Agency Assigned must include .
  • Invitation must include .
  • Reactivation must include .

Under the body the editor says, for example, "Body must include the merge field so the candidate can open their application form", and the template will not save until you add it. Your organisation normally already has a template in these categories, so edit that one rather than adding another.

When a merge field has no value

Most fields are optional. If a value is missing when the message is sent, the field shows blank. A few fields are required, because the email is useless without them. If a candidate email uses one of these and the information is missing, Recruit does not send the email.

Template categoryRequired fields
Reopen Application FormThe reopen link
Interview Booking ReminderThe scheduling link
Interview Upcoming Reminder, Interview Slot ReminderThe interview date and time
Video Interview Invitation, Video Interview ReminderThe video interview link
Offer, Offer Expiring Reminder, Offer AcceptedThe offer link
Reference Request, Reference Form ReminderThe reference link
Onboarding Welcome, Onboarding Task NotificationThe onboarding link
Onboarding ReminderThe onboarding link and the task title

A field only counts as required when the template actually uses it. The acknowledgement email a candidate gets when they apply is never blocked.

An email that is held back this way appears on the candidate's Communications tab with the status Failed. Hover over it to see "Not sent" followed by the names of the missing fields. It cannot be resent until the missing information has been added. The job's recruiters also get an email called "Candidate email not sent for" followed by the job title, if their Candidate emails not sent notification is on. If the job has no recruiter, the job's hiring lead gets it. See "Notification preferences" for that switch.

Finding templates with broken merge fields

Go to Settings, then Automations & Communication, then Broken merge fields. The page lists every email template and offer document that contains a field that will never fill in. Each row shows the template, its type, the part it appears in (subject or body), the merge field and the problem. The problems are:

  • An unconverted field from the previous system, which will not be filled in.
  • A field that this type of message cannot fill.
  • A name that is not a Recruit merge field, so no message can fill it.
  • A merge field that is not written correctly, so candidates would see it exactly as typed.

Fix the template and it drops off the list. When nothing is wrong the page says "No broken merge fields". Anyone who can manage templates can open it.