Skip to main content
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": "[email protected]",
    "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"
    }
  }
}
REFERENCING DATA OBJECT VARIABLESCourier 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}
VARIABLE NAMING CONVENTIONSWhen 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 profile object 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": "[email protected]",
  "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"
    }
  ]
}
PRECEDENCE OF PROFILE DATAIf 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.
  • {var "datetime.year"}: Load the current year in your notification.

​
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:
Example of Variable Replacement in Rendered Preview

Example of Variable Replacement in Rendered Preview

The Template 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.
Text Block With Variables

Text Block With Variables

​
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.
Email Subject With Variables

Email Subject With Variables

Email Channel Settings

Email Channel Settings