Introduction

Tokens in CiviPlus are placeholders that dynamically insert data from the CRM records into emails, letters, and other communications. This powerful feature allows you to personalise messages for each recipient without manually editing each message.

What Are Tokens?

A token is a special code that references a data field in CiviPlus. When the message is sent or rendered, the token is replaced with the actual data for that specific contact, event, or case.

For example:

Dear {contact.first_name}, will become Dear John when the email message is sent.

Tokens can be used in a number of different ways:

Email messages
PDF letters
Mailing labels
Contribution receipts
Event confirmations

In this article we will focus on Email messages, but you can search the Knowledge Base to find out more about how to use Tokens for other use cases.

Inserting Tokens Into Emails

It's really easy to add tokens when composing an email message in CiviPlus. As described here, there are two types of mailings that can be created using either the traditional template builder, or the "drag and drop" email builder called Mosaico. For the purpose of this article we will insert Tokens into a message created using the Mosaico tool, but the technique is exactly the same for emails generated in the traditional email builder.

Let's create a new template (but obviously you could edit an existing one) - navigate to Mailings -> New Mailing and enter a name for the email template - in this case it is a Monthly Newsletter. Complete the Campaign (if needed), From (if needed) and Recipients fields, and then move to the Subject line where we can add some personalisation using Tokens. You can create the subject line as usual, and then move your cursor to the place where you want to insert the token. When you click the </> Tokens link you will see a drop down list of all the tokens available in the system. There are hundreds of them, but luckily you can just start to type the one you want and the list will be searched. In this case we enter "first" into the search bar and the Contact -> First Name Token is highlighted. Simply click it to insert the Token into the appropriate place in the Subject line.

That's it! You've added personalisation to the email message so that the subject line

"Hi {contact.first_name}! Here's the monthly newsletter that you subscribed to."

will become

"Hi John! Here's the monthly newsletter that you subscribed to."

when the email message is sent (assuming the contact's first name is John!).

Commonly Used Tokens

Here is a list of frequently used tokens that you might want to use within a Newsletter email.

Token	Description
`{contact.first_name}`	Contact's first name
`{contact.last_name}`	Contact's last name
`{contact.email}`	Contact's email address
`{domain.name}`	Your organisation's name
`{domain.address}`	Your organisation's postal address
`{action.unsubscribeUrl}`	Link for the contact to unsubscribe

The screen shot below shows some of these Tokens added into the content blocks of the Newsletter.

The screenshot below shows what the email might look like when received by Rebecca Walker.

Where Tokens Can Be Used

While tokens are primarily used in email mailings, they can also be used in:

Event confirmation messages
Contribution receipts
Membership renewal emails
Custom PDF letters (via Print PDF Letter)

Note: Some tokens (like {action.unsubscribeUrl}) only work in specific contexts such as email mailings.

Best Practices for using Tokens

Test before sending: Always send test messages to yourself or your team to make sure that the Tokens are being replaced in the way that you want.
Fallback values: Consider what happens if a token field is empty for a contact - will the message look strange if you use {contact.middle_name} for some reason, and the contact doesn't have a Middle Name?
Avoid overuse: Use just enough personalisation to enhance readability without overwhelming the message.
Check formatting: Preview how long names or unusual field values affect the layout.