Using klaviyo

This guide provides a step-by-step walkthrough on setting up Klaviyo with Firmhouse to send email notifications to your customers.

​

What Does the Integration with Klaviyo Do?

When enabled, Firmhouse sends a message to Klaviyo with metadata about an event. An event can be a new subscriber signing up, a new order getting created, etc. These events correspond with the same email templates that Firmhouse would send if Klaviyo was disabled. When an event is sent to Klaviyo, it’s recorded as a “metric” there. To turn metrics into emails, you need to create flows in Klaviyo that run based on these metrics.

​

Overview

Here’s an overview of the steps to enable and set up Klaviyo:

1. In Firmhouse, go to Apps > Klaviyo > Configure
2. Enable your Klaviyo app
3. Add your Klaviyo API key
4. Enable the “Use Klaviyo events editor” checkbox (this will replace your existing email templates in the templates editor)
5. Save the settings (at this point, the Klaviyo connection is enabled in Test mode)
6. Edit the templates in Firmhouse
7. Test event triggers
8. Set up your flows in Klaviyo
9. Change the communication channel of the project from “Email” to “Klaviyo”

​

Setting Up the Klaviyo App

​

Open the Klaviyo App

Go to the Klaviyo app in the Firmhouse menu: Apps > Klaviyo > Configure.

​

Enable the Klaviyo App

If you’ve previously tried to set up the app and then decided to disable it, you will need to enable it again by clicking on Enable Klaviyo app.

​

Add the Klaviyo API Key and Enable the Events Editor

To link Firmhouse to Klaviyo, you will need your Klaviyo API key (learn how to get it). After you enter the API key, select the checkbox Use Klaviyo events editor. This will enable the template editor for all the events that Firmhouse sends to Klaviyo. When you’re ready, click Save. Test mode: At this step, you should see the app Status show Test mode. This means the app and Klaviyo events editor are enabled, but the communication channel for the project is still set to emails. This gives you the opportunity to prepare and test the Klaviyo event template without disrupting your working email templates.

​

Edit the Templates

Go to Settings > Email configuration to find all events Firmhouse can send to Klaviyo. The top bar will show if the Klaviyo integration is active or not. The key difference between Klaviyo and email templates is that Klaviyo templates need to be in valid JSON format. When editing the templates, you can use the same Liquid tags that are used with email. Set a Klaviyo event name for each event. Flows in Klaviyo use these metrics as a starting point, reading from the data in the template.

​

Test the Events

Test your events to make sure they are formatted correctly and contain the information you expect. Click on Send test Klaviyo event. Enter your email address in the pop-up and you will receive the event with some example data.

​

Creating Klaviyo Flows

Once your event payloads are configured in Firmhouse, it’s time to build the corresponding Klaviyo flows so your customers can receive their emails.

​

Create Klaviyo Metrics

Each event and payload in Firmhouse will have a corresponding metric and mailing flow in Klaviyo. The easiest way to create the metrics is by sending a test event from Firmhouse to Klaviyo. Open your Firmhouse Email configuration page, select one of the templates, and click on Send test event to Klaviyo. After you send the test event, you should be able to see a new API metric in your Klaviyo dashboard:

​

Create a New Flow

In your Klaviyo dashboard, navigate to Flows and select “Create flow”. You’ll need to select Build your own and provide a relevant name.

​

Configure the Flow Trigger

Link your new metric to this flow. You will find the metric in Your metrics section on the right side of the screen: Once you select the trigger, you will be asked if you want to add any filters to it. You won’t need to, so you can skip this step. Confirm and save the configuration.

​

Add an Email to Your Flow

Drag and drop the email block from the left-hand menu and link it to your trigger. The key configuration options are:

1. Email name - an internal value to help identify the template
2. Subject line - the subject customers will see in their inbox
3. Preview text - the preview text customers will see
4. Skip recently emailed profiles - make sure to disable this so all emails get sent
5. Template - select or build your email template

​

Customize the Email Template

Select a template from the Klaviyo library or create your own. Klaviyo will open the email editor so you can adjust the content. Add your own images, branding and copy to make it your own. Use the Preview & test menu to see your event properties and inject dynamic data into your email:

​

Insert Simple Values

To make the email more personable, copy values from your trigger and paste them into the email template. For example, use the name property on the first email line.

​

Use URLs

Add buttons that send customers to the Self Service Center using the SelfServiceCenterUrl property:

​

Parse Event Property Lists

For complex properties like product lists, use the Content repeat function in Klaviyo to loop over all items.

​

Go Live

​

Set Your Flow to Live

Once you’ve finished editing your template, change the status of the email or use the Review and turn on feature to let the flow be triggered by all events sent from Firmhouse.

​

Change the Communication Channel

When you’re ready to complete the switch, go to Settings > Subscription model > Notification services and change the channel to Klaviyo. Scroll down and click Update project.

​

Important: Mark Firmhouse Flows as Transactional

Klaviyo is primarily used to send marketing emails and allows subscribers to unsubscribe. An unwanted side-effect is that it can prevent transactional emails from being sent. To ensure all Firmhouse transactional emails are delivered, contact Klaviyo support and ask them to mark the flows containing Firmhouse emails as transactional. See this Klaviyo help article for more information.

​

Troubleshooting

If events don’t arrive in Klaviyo, the most likely cause is a problem with the JSON formatting of the template. This should show up as an error in your project Notifications. Try an online JSON validator to highlight where the problem is.

​

Additional Resources

• Example templates for Klaviyo integration
• Available Liquid tags to provide dynamic content to Klaviyo