Inserting Data with Variables
Personalize your Courier notifications using variables from different data sources and insert them into various parts of a notification.
Read More: JSONPath Expressions
Data Sources for Substitution Variables
Courier enables you to use variables to insert dynamic values into your notifications from five sources:
The Data Object
The Data object is an optional property of the send command that allows you to pass arbitrary key-value pairs into your message template.
{
"customer": {
"id": "cust_abc123",
"name": "Acme Corporation",
"email": "contact@acme.com",
"plan": {
"id": "plan_enterprise",
"name": "Enterprise",
"price": {
"currency": "USD",
"amount": 99.99,
"interval": "month"
},
"features": [
"Unlimited users",
"Priority support",
"Custom branding"
]
}
},
"usage": {
"period": {
"start": "2024-05-01",
"end": "2024-05-31"
},
"activeUsers": 250,
"storage": {
"used": 2048,
"limit": 5120,
"unit": "GB"
},
"apiCalls": 125000,
"customDomains": 3
},
"billing": {
"nextInvoiceDate": "2024-06-01",
"balance": {
"currency": "USD",
"amount": 0
},
"paymentMethod": {
"type": "CreditCard",
"lastFour": "1234"
}
}
}
Courier automatically references the data path by default. You do not need to include data in your variable path if the key-value pair is at the top level of the Data object. Nested values need to begin the path where the data value originates, e.g. {first_layer.second_layer}
When using variables in your notification content, ensure that the variable names are in either camelCase or snake_case format. Using dashes or other unsupported characters in variable names will result in a rendering error.
- Valid variable name:
{firstName}or{first_name} - Invalid variable name:
{first-name}
The User Profile
User Profile data can be sourced from two places:
- The
profileobject in the Send API request. - The User Profile associated with the recipient ID, created via the Profiles API.
{
"userId": "user456",
"name": {
"firstName": "Jane",
"lastName": "Doe",
"middleName": "Elizabeth"
},
"email": "jane.doe@example.com",
"phone": "+1 555 9876543",
"dateOfBirth": "1992-11-23",
"gender": "Female",
"address": {
"street": "123 Main St",
"city": "Anytown",
"state": "CA",
"zipCode": "12345",
"country": "USA"
},
"locale": "en-US",
"timezone": "America/Los_Angeles",
"preferences": {
"language": "en",
"currency": "USD",
"theme": "dark"
},
"account": {
"createdAt": "2021-08-15T09:30:12Z",
"plan": "basic",
"status": "active"
},
"subscription": {
"id": "sub_xyz789",
"startDate": "2023-06-01",
"endDate": "2024-05-31",
"paymentMethod": {
"type": "CreditCard",
"lastFour": "5678"
}
},
"socialProfiles": {
"twitter": "https://twitter.com/janedoe",
"linkedin": "https://linkedin.com/in/janedoe"
},
"permissions": [
"view_reports",
"manage_users",
"create_projects"
],
"integrations": [
{
"name": "GitHub",
"enabled": true,
"credentials": {
"accessToken": "abc123def456"
}
},
{
"name": "Slack",
"enabled": false
}
],
"teams": [
{
"id": "team_abc123",
"name": "Marketing Team",
"role": "member"
},
{
"id": "team_def456",
"name": "Engineering Team",
"role": "admin"
}
]
}
If a conflict arises between the profile object in the Send API request and the User Profile, the profile object in the Send API request takes precedence.
Read More: JSON Paths and Variables Basics
Built-in Variables
Courier provides a set of predefined variables that are automatically populated with relevant data during the send process. These built-in variables can be used in your notification content and settings.
The available built-in variables include:
{courier.environment}: The environment, e.g., "production" or "test".{courier.scope}: The notification scope, e.g., "published" or "draft".{event}: The event associated with the notification.{messageId}: The unique identifier for the message.{openTrackingId}: The tracking ID for email open events.{recipient}: The recipient ID.{subscriptionTopicId}: The ID of the subscription topic, if applicable.{template}: The name of the template used for the notification.{unsubscribeTrackingId}: The tracking ID for unsubscribe events.{urls.opened}: The URL for tracking email opens.{urls.unsubscribe}: The unsubscribe URL.{urls.preferences}: The URL for managing the user's notification preferences.
Tenant Object
The Tenant object can be referenced to insert values specific to the tenant or organization, such as the tenant name.
Brand Object
The Brand object can be referenced to insert variables based on the active brand used in the notification. These variables can include brand names, colors, logos, or other branding elements.
Using Variables in Notifications
Variables can be used to insert data into:
- Notification content across all types
- Content Blocks (Text, Action, Markdown, Quote, Template, List)
- Handlebars code (Template blocks, Email templates, Brands)
- Email subject line and addresses (From, To, CC, BCC)
- Notification Conditions to control notification sending
- Channel Conditions to enable or disable specific channels
- Filters to conditionally show or hide content blocks
The Notification Designer supports using external data in various places, such as:
Inserting Variables Into Content Blocks
To insert variables into Content Blocks, enclose the variable name within single curly brackets: {variable_name}. Properly formatted variables inside Text, Markdown, Quote, and List Blocks will be highlighted in green.
Inserting Variables into Handlebars
To insert data into Handlebars, use double curly brackets {{ }} around the variable, following the same paths as in Content Blocks. However, you must include the Handlebars var or path helper to insert a variable from your JSON event:
- Data object:
{{var "variable_name"}} - Profile data:
{{var "profile.variable_name"}}
Handlebars code is used in the Template Content Block type, Brand Templates, and the Handlebars override within Email Notifications.
Inserting Variables into Email Fields
In addition to the Handlebars Template override, variables are supported in the Subject line, From address, Reply-To, CC, and BCC fields in the email channel settings.
