Skip to main content

Best practices

Follow these recommended approaches when implementing email and SMS template customization.

Start with a complete default set​

Ensure you have a full set of default templates (without brand qualification) before adding brand-specific or locale-specific variants. This ensures every user receives a message, even if they don't match a specific template.

Be consistent with brand values​

Since brand is a free-form field (up to 25 characters, no spaces), establish a naming convention and document it internally. Typos in brand values when creating users cause those users to fall back to non-branded templates.

Test the cascade​

Before going live, create test users with different combinations of locale and brand to confirm they receive the expected templates. Verify that fallback behavior works as intended for edge cases, such as:

  • Users with an unrecognized brand
  • Users with a locale you haven't created templates for
  • Users with neither brand nor locale set

See practical examples for scenarios to test against.

Plan your locale strategy​

Decide whether you need regional variants (for example, en-GB versus en-US) or can use a single base locale (for example, en) for each language. Using base locales simplifies template management while still serving users with regional locale settings through the locale fallback mechanism.

Consider your user creation flow​

Determine at what point in your app's user journey you capture or assign locale and brand values. Common approaches include:

  • Deriving locale from the user's browser settings or app language preference
  • Deriving brand from the context in which the user registered
  • Setting defaults at creation time and allowing users to update their preferences later

Balance specificity with maintainability​

While creating many template variants allows precise targeting, each variant must be maintained. Start with the minimum viable set of templates and expand as your requirements become clearer. See designing your template strategy for the available options.

Roll out gradually​

You can introduce branding and localization gradually without affecting existing users. Since both locale and brand are optional, existing users without these values continue to receive your current default templates unchanged. New users can be created with locale and brand values immediately, and you can update existing users' records over time.

Next steps​