Tokens
A token is a marker Pyn replaces when a message is formatted for one recipient. Type @ in the editor to insert one; in a Raw HTML email write it as a Liquid tag, {{ principal.preferredName }}. principal tokens are about the enrolled employee, recipient tokens about the person receiving the message; in a message to the employee the two are the same person.
When a value is missing, the token renders its fallback text, shown in the tables below, unless you set your own fallback on the token. Names, departments and job titles come from the employee record in Directory.
Tokens in the editor
Section titled “Tokens in the editor”| Token | Value | Fallback |
|---|---|---|
date.reference |
The enrollment’s reference date | reference date |
principal.preferredName |
Preferred name, else the first word of the display name | Employee |
principal.firstName |
First word of the display name (or legal name) | Employee |
principal.preferredFullName |
Preferred name plus the surname from the display name | Employee |
principal.legalName |
Legal name, else display name | Employee |
principal.jobTitle |
Job title | Job Title |
principal.department |
Department | department |
principal.location |
Location | location |
principal.startDate |
Start date | start date |
principal.startDate.dayAfter |
The day after the start date | start date |
principal.startDate.nextBusinessDay |
The next weekday after the start date | start date |
principal.tenure |
Whole years since the tenure date (or start date) at send time: “1 year”, “3 years” | tenure |
principal.birthday |
Birthday as day and month, for example “28 Jul” | Birthday |
principal.nextBirthday |
The next birthday on or after the reference date | next Birthday |
principal.nextAnniversary |
The next start-date anniversary on or after the reference date | next Anniversary |
principal.managerName |
Manager’s display name | Manager |
principal.managerPreferredName |
Manager’s preferred name | Manager |
principal.managerEmail |
Manager’s work email | manager email |
principal.buddy.name |
Buddy’s display name | Buddy |
principal.buddy.preferredName |
Buddy’s preferred name | Buddy |
principal.buddy.preferredFullName |
Buddy’s preferred name and surname | Buddy |
principal.buddy.email |
Buddy’s work email | buddy email |
principal.buddy.startDate.nextBusinessDay |
The weekday after the buddy’s start date | start date |
principal.hrbp.name |
HR business partner’s display name | HRBP |
principal.hrbp.preferredName |
HR business partner’s preferred name | HRBP |
principal.hrbp.preferredFullName |
HR business partner’s preferred name and surname | HRBP |
principal.hrbp.email |
HR business partner’s work email | HRBP email |
recipient.preferredName, recipient.firstName, recipient.preferredFullName, recipient.legalName |
As above, for the recipient | Employee |
recipient.department, recipient.location |
As above, for the recipient | department, location |
recipient.startDate |
The recipient’s start date | start date |
recipient.birthday, recipient.nextBirthday, recipient.nextAnniversary |
As above, for the recipient | Birthday, next Birthday, next Anniversary |
recipient.surveyLink |
A link stored on the recipient’s record; renders as a link, or nothing |
The Subject of an email offers a smaller set: the preferred name, birthday, next birthday and next anniversary of the principal and the recipient. A Jira ticket’s Summary and Description offer principal tokens only.
Tokens for Raw HTML
Section titled “Tokens for Raw HTML”A Raw HTML email resolves every token above by its Liquid name, plus these:
| Token | Value | Fallback |
|---|---|---|
company.name |
The workspace’s company name | company |
date.today |
The send date | today |
date.tomorrow |
The day after the send date | tomorrow |
principal.name, recipient.name |
Display name | Employee |
principal.email, recipient.email |
Work email | email address |
principal.personalEmail, recipient.personalEmail |
Personal email | personal email address |
principal.endDate, recipient.endDate |
Termination date | end date |
principal.city, principal.country, recipient.city, recipient.country |
City and country | city, country |
A Liquid name Pyn does not know is left in the email as typed.
Custom and employee-field tokens
Section titled “Custom and employee-field tokens”custom.<column>: a column from the mail-merge spreadsheet used to enrol the person, named in camel case (Start Locationbecomescustom.startLocation). Insert it with Insert widget, Custom Token. Falls back to the column name. See Enroll from a spreadsheet.- Employee field tokens: any field on the employee record, chosen with Insert token, Employee Field, applied to the principal or the recipient, with an optional fallback you type. Without one, a missing value renders as nothing.
Formatting
Section titled “Formatting”- Dates render in the recipient’s locale as weekday, day, month and year, for example “Thu, 22 Oct 2026”. Birthdays render as day and month.
date.todayanddate.tomorroware taken from the delivery’s scheduled time; in a preview with no send time they show their fallback.- Tenure is rounded to whole years, so someone eleven months in reads “1 year”.
- A token inside a bold or coloured run keeps that formatting.
Names Pyn no longer fills
Section titled “Names Pyn no longer fills”The following names from Pyn Classic are accepted but render as nothing: date.nextBusinessDay, every manager.* token (use principal.managerName, principal.managerPreferredName and principal.managerEmail), principal.homeAddress, principal.employeeNumber, principal.employmentType, principal.mobilePhone, principal.brand, principal.buddy.jobTitle, principal.buddy.location, principal.buddy.startDate, principal.buddy.startDate.dayAfter, principal.returnsFromLeaveOn, the recipient equivalents of those, and recipient.startDate.dayAfter and recipient.startDate.nextBusinessDay.
Related
Section titled “Related”- Format a message for inserting tokens, custom tokens and employee fields.
- Choose recipients and Cc for who principal and recipient are on each step.
- Enroll from a spreadsheet for custom token columns.