Klaviyo Integration

Why Klaviyo Integration Matters

Klaviyo provides powerful email marketing capabilities with advanced segmentation, flows, and analytics. The ILLIXIS integration lets you generate campaigns using AI content and send them directly to your Klaviyo lists without switching platforms.

Connection Setup

Getting Your Klaviyo API Key

1. Log in to Klaviyo at klaviyo.com
2. Go to Settings > API Keys
3. Under Private API Keys, click Create Private API Key
4. Give it a name like "ILLIXIS Integration"
5. Copy the API key (starts with pk_)

Connecting to ILLIXIS

1. Go to Settings > Integrations in ILLIXIS
2. Find the Klaviyo section
3. Paste your Private API Key
4. Click Connect

ILLIXIS validates the API key by checking your Klaviyo account details. If successful, you'll see your Klaviyo account name displayed as connected.

What Happens During Connection

When you connect Klaviyo, ILLIXIS automatically:

• Validates the API key against Klaviyo's API
• Stores your account ID and name
• Registers webhooks for bounce, unsubscribe, and spam complaint events
• Enables campaign sending from the Email Campaign Builder

Sending Campaigns to Klaviyo

From the Email Campaign Builder

1. Go to Email Campaigns (/email-campaigns/)
2. Select content for your email digest (articles, products, or both)
3. Click Generate Email Campaign
4. Review the generated email (subject lines, preview text, HTML)
5. Click Publish to Klaviyo

Publishing Options

When publishing, you choose:

Audience List Select which Klaviyo list receives the campaign. The dropdown shows all your active lists with subscriber counts.

Subject Line Choose from the AI-generated subject line options, or write your own.

Send Options

• Send Now - Campaign goes out immediately
• Save as Draft - Campaign created in Klaviyo but not sent (you can schedule it manually in Klaviyo)

What Happens Behind the Scenes

ILLIXIS follows Klaviyo's API workflow:

1. Create Template - HTML content uploaded as a Klaviyo template
2. Create Campaign - Campaign created with your subject, preview text, and sender info
3. Assign Template - Template linked to the campaign message
4. Send (Optional) - If "Send Now" selected, campaign is sent immediately

Your campaign appears in Klaviyo's Campaigns dashboard immediately.

Sender Information

ILLIXIS uses tenant-configured sender details:

• From Name: Your business brand name (from Tenant Settings)
• From Email: Tenant owner's email, or hello@{your-domain} if domain configured

Make sure these are set correctly before sending your first campaign.

Campaign Metrics Tracking

Viewing Campaign Performance

After sending a campaign, ILLIXIS syncs performance metrics from Klaviyo:

1. Go to Email Campaigns
2. Find your sent campaign
3. Click View Campaign
4. Click Refresh Metrics

Available Metrics

Delivery Metrics

• Delivered count
• Bounce count and bounce rate

Engagement Metrics

• Opens (total and unique)
• Open rate (percentage)
• Clicks (total and unique)
• Click rate (percentage)
• Click-to-open rate (percentage)

List Health Metrics

• Unsubscribes and unsubscribe rate
• Spam complaints and complaint rate

Metrics Update Frequency

Metrics don't auto-refresh. Click Refresh Metrics when you want updated numbers. Klaviyo typically updates metrics within 5-15 minutes of campaign send.

Campaign Status

Campaigns show one of these statuses:

• draft - Created but not sent
• sending - Currently being delivered
• sent - Delivery complete
• error - Sending failed (check the campaign detail page for error messages)

Metrics are only available for campaigns with sent status.

Automation Schedule

ILLIXIS automatically syncs data from Klaviyo on a recurring schedule. You don't need to manually refresh most data.

Campaign Metrics Sync

Daily at 7:30 AM UTC

All sent campaigns have their metrics updated automatically. This includes opens, clicks, bounces, unsubscribes, and spam complaints. You can still click Refresh Metrics for on-demand updates.

Suppression List Sync

Daily at 4:00 AM UTC

Unsubscribes, bounces, and spam complaints are synced from Klaviyo to your ILLIXIS suppression list. This ensures cross-platform compliance even if webhook delivery fails.

Flow Performance Metrics

Every 6 hours

If you have Klaviyo Flows connected, their performance metrics are updated four times daily (12:00 AM, 6:00 AM, 12:00 PM, 6:00 PM UTC).

List and Segment Counts

Daily

Subscriber counts for your Klaviyo lists and segments are refreshed once per day. If you need real-time counts after a major list import, disconnect and reconnect the integration to force a refresh.

Timezone Note

All scheduled syncs run in UTC. If you're in a different timezone, plan accordingly. For example, 7:30 AM UTC is:

• 2:30 AM EST / 3:30 AM EDT
• 11:30 PM PST / 12:30 AM PDT (previous day)
• 8:30 AM CET / 9:30 AM CEST

List Management

Fetching Your Klaviyo Lists

ILLIXIS fetches your audience lists when you open the campaign publish modal. Lists include:

• List ID (internal Klaviyo identifier)
• List name
• Subscriber count

Lists are cached locally to reduce API calls.

Refreshing Lists

If you add a new list in Klaviyo, disconnect and reconnect the integration in ILLIXIS Settings to refresh the cached list data.

Suppression Management (Automatic)

Webhook-Based Suppression Sync

When you connect Klaviyo, ILLIXIS registers webhooks for these events:

• event:klaviyo.email_bounced
• event:klaviyo.email_marked_as_spam
• event:klaviyo.unsubscribed
• event:klaviyo.unsubscribed_from_list

When these events occur in Klaviyo, the webhook notifies ILLIXIS, which updates your tenant's suppression list automatically.

Why This Matters

If a subscriber unsubscribes via Klaviyo, ILLIXIS knows not to send them email through other platforms (Mailchimp, Resend). This protects your sender reputation across all connected email platforms.

Manual Suppression Sync

If webhooks fail or you need to backfill suppressions:

1. Go to Email & Automation > Email Compliance
2. Click Sync Klaviyo Suppressions

This fetches all suppressed profiles from Klaviyo and updates your ILLIXIS suppression list.

Campaign Templates

Template Creation

ILLIXIS creates a new Klaviyo template for each campaign. Templates are named:
```
ILLIXIS Campaign - {subject line} - {timestamp}
```

This avoids template name collisions when sending multiple campaigns.

Template Type

Templates use editor_type: CODE, meaning they're HTML-based (not drag-drop blocks). This preserves the exact HTML generated by ILLIXIS.

Viewing Templates

Templates appear in Klaviyo under Email > Templates. You can reuse them for manual campaigns if needed.

Smart Sending

Campaigns sent through ILLIXIS have Smart Sending enabled by default. This prevents subscribers from receiving multiple emails within a short time window, improving engagement rates.

Troubleshooting

"Klaviyo not connected" Error

Cause: API key validation failed or connection was deleted.

Fix: Go to Settings > Integrations and reconnect Klaviyo with a valid Private API key.

"Failed to create template" Error

Cause: HTML content exceeds Klaviyo's size limits, or API key lacks template creation permissions.

Fix:

• Check that your API key has full read/write permissions
• Reduce campaign content size (fewer articles/products)

Metrics Show Zero

Cause: Campaign was sent recently and metrics haven't updated yet, or campaign status is draft.

Fix: Wait 15 minutes after send, then click Refresh Metrics. Verify campaign status is sent in Klaviyo.

Webhook Registration Failed

Cause: API key lacks webhooks:write or events:read scope.

Fix: Create a new Private API key with full permissions. Disconnect and reconnect the integration.

Campaign Shows "Error" Status

Cause: Various issues can cause send failures.

Fix: View the campaign detail page. The error message explains what failed. Common issues:

• Invalid list ID (list was deleted in Klaviyo)
• Missing sender email (configure tenant owner email)
• API rate limit (wait 60 seconds, try again)

Rate Limits

Klaviyo applies rate limits per account. If you hit rate limits, wait 60 seconds before retrying the operation.

Disconnecting Klaviyo

To remove the Klaviyo connection:

1. Go to Settings > Integrations
2. Find the Klaviyo section
3. Click Disconnect

This deletes the stored API key and cached list data. Webhooks remain active in Klaviyo until you manually delete them from Klaviyo's webhook settings.

Sequence Builder Integration

Klaviyo campaigns sent through ILLIXIS are standalone campaigns for one-time sends.

For automated sequences, you can push ILLIXIS sequences directly to Klaviyo as native flows. See Help Guide 172 (Push Sequences to Klaviyo) for full details on how to convert your visual sequences into Klaviyo flows with one click.

Preference Learning

ILLIXIS tracks campaign performance from Klaviyo (open rates, click rates) but does not yet use this data for preference learning. This feature is planned for a future release.

Best Practices

Test with a Draft First
Send your first campaign as a draft. Review it in Klaviyo before scheduling send. This verifies template rendering and sender info.

Use Descriptive Subject Lines
Subject lines become the campaign name in Klaviyo. Make them descriptive so you can identify campaigns later.

Check Sender Email
Before sending, verify your tenant owner email is configured. Go to Settings > Team to set the owner's email address.

Monitor Metrics Weekly
Check campaign metrics 24-48 hours after send. Look for high bounce or unsubscribe rates, which signal list quality issues.

Don't Send Too Frequently
Klaviyo's Smart Sending helps, but space campaigns at least 2-3 days apart to avoid fatigue.

Related Features

• Email Campaign Builder - Generate campaigns with AI content
• Email Compliance - CAN-SPAM/GDPR suppression management
• Mailchimp Integration - Alternative email platform
• Resend Integration - Transactional and broadcast emails
• Visual Sequence Builder - Multi-step email automation (not Klaviyo-based)