Klaviyo

#What the connection does

With Klaviyo connected, every email a shopper leaves in your quiz also goes to your Klaviyo account:

• The shopper’s profile, with their answers as profile properties you can segment on.
• A Teacup Quiz Completed event with their products, prices, photos and a one-click cart link, to start a flow from.
• A subscription to the list you choose, only for shoppers who ticked your marketing box.

Only emails that arrive while Klaviyo is connected are sent: earlier ones stay on the Emails page. To bring those over, use Export CSV on the Emails page and import the file in Klaviyo.

#Connect with one click

1. Open Integrations in Teacup Quiz.
2. In the Klaviyo section, click Connect Klaviyo. Klaviyo’s consent screen opens in the whole window.
3. Sign in to Klaviyo if asked, check that it’s the right account, and allow access.
4. You’re back on Integrations, with “Klaviyo connected. Send a test event to check it end to end.”

Teacup Quiz asks Klaviyo for access to read your account’s name (to show where emails go), send events, create and update profiles, read your lists and add profiles to them, and subscribe the shoppers who agreed. The access keeps itself up to date, so you never need to reconnect for that.

• If you don’t allow access, you see “Klaviyo wasn’t connected: access wasn’t allowed in Klaviyo.”
• If anything else goes wrong, or you spend more than 10 minutes on Klaviyo’s screen, you see “Klaviyo couldn’t be connected. Please try again.” Click Connect Klaviyo again.

#Connect with a private API key

If you’d rather manage access yourself, use a private API key.

1. In Klaviyo, open Settings → API keys and click Create private API key.
2. Name it, for example “Teacup Quiz”, and choose Full access. Or choose a custom key with full access to Events, Lists, Profiles and Subscriptions.
3. Create the key and copy it. It starts with pk_.
4. In Teacup Quiz, open Integrations, click Use a private API key instead and paste the key into Private API key.
5. Click Connect with key.

The key is stored encrypted. The page only shows its first and last characters, like pk_…a1b2.

#When Klaviyo is connected

The Klaviyo section then shows:

• Connected, your Klaviyo account’s name and how you connected: “connected with one click” or “private key pk_…”.
• “Last quiz email sent to Klaviyo: {time}”, or “No quiz emails sent to Klaviyo yet.”
• A warning when Klaviyo didn’t take the last email. See When Klaviyo doesn’t take an email.
• Subscribe shoppers who agree to, to choose a list.
• Send a test event and Disconnect Klaviyo.

#Choose a list for subscribers

In Subscribe shoppers who agree to, pick the Klaviyo list for shoppers who tick your marketing box. It saves right away, with “Subscribers go to …” and the list’s name.

• Only shoppers who tick the box in the quiz’s email step are subscribed, and only to email marketing. Teacup Quiz never subscribes anyone to SMS, even when it sends their phone number.
• Shoppers who don’t tick it still get a profile and the event, but no subscription.
• No list (profiles and events only) subscribes no one: “Subscribers won’t be added to a list”.
• Klaviyo records “Teacup Quiz” as the subscription’s source.

#Send a test event

Click Send a test event to check the connection before any shopper takes the quiz. Teacup Quiz sends one Teacup Quiz Completed event to the email under Settings → Send to, or to your store’s email if that’s empty. You see “Test event sent to … It shows in Klaviyo within a minute or two.”

• It creates the Teacup Quiz Completed metric in Klaviyo, so you can build flows right away.
• It carries two example products, “Example product” and “Another product”, an example answer and test set to true, so you can design your email with realistic data.
• It doesn’t change the profile’s properties and doesn’t subscribe anyone.

If there’s no email to send it to, the button is greyed out, with “The test event goes to the email Teacup writes to. Add one in Settings.”

#Exactly what Teacup Quiz sends

The event: Teacup Quiz Completed

One event per quiz run, dated when the shopper left their email. Its properties:

The products are worked out from your published quiz, the same way as the results page. Products that can’t be bought right now are left out and the picks recalculated, so the email matches what the shopper saw. Prices are in your store’s currency. step is the routine step’s name (empty for best matches), and good_for says why the product fits. On result-page quizzes both are empty. When the shopper got no products, the product properties are empty or left out.

The profile

A later quiz updates these properties, so a profile shows the shopper’s latest answers. The subscription is sent as described in Choose a list for subscribers.

#Build the “Email shoppers their routine” flow

The Email shoppers their routine section on Integrations has a ready-made email block. It lists the shopper’s products with photos, steps and prices, and a button that adds them all to the cart. Set it up once:

1. In Teacup Quiz, click Send a test event, so the trigger exists in Klaviyo.
2. In Klaviyo, open Flows → Create flow → Build your own, name the flow and pick the trigger Teacup Quiz Completed.
3. Add an email. A good subject: Your routine for {{ event.routine_for|default:'you' }}.
4. Back in Teacup Quiz, click Copy the email block. You see “Copied. Paste it into an HTML block in Klaviyo.” If copying is blocked, select the text in Email block (HTML) and copy it yourself.
5. In the Klaviyo email, drag in an HTML block and paste.
6. Preview the email with your test event, then set the flow to Live.

The app suggests the subject Your routine for {{ event.routine_for }}. Because routine_for is empty when the answer has no Good for text, the version above, with a fallback of “you”, never ends in “for”.

What the block shows:

• The heading “Your routine for oily skin”, or just “Your routine” when there’s nothing to add, then “Picked for you from your answers.”
• Each product with its photo, “Step 1 · Cleanser” when the quiz builds a routine, its name linked to the product, “Good for …” and its price.
• A button, “Shop the whole routine · $86.00”, that puts every product in the cart.

#When Klaviyo doesn’t take an email

If Klaviyo is busy, down or can’t be reached, the email waits and Teacup Quiz sends it again by itself, after 2, 4, 8 minutes and so on, for about a day. The Klaviyo section shows what’s happening:

Waiting emails are dropped when you disconnect Klaviyo, when your plan no longer includes it, or after about a day of tries. Every message and its fix: Klaviyo isn’t receiving emails.

#Disconnecting, and changing plans

Click Disconnect Klaviyo and confirm “Stop sending quiz emails to Klaviyo?” with Disconnect. You see “Klaviyo disconnected”. Emails waiting to be resent are dropped, and with one-click connect, Teacup Quiz gives up its access in Klaviyo. Your profiles, events and lists in Klaviyo stay.

To switch between one-click and a private key, or to another Klaviyo account, disconnect first, then connect again. Reconnecting the same account with one click keeps your list.