Klaviyo: Telltide Seed Address Guide

Klaviyo's identity model is email-first: one email address maps to one profile. This is clean for seed management - use + subaddressing to create distinct profiles (e.g., monitor+seed1@yourdomain.com) that all deliver to the same inbox. Each variant is a genuinely separate Klaviyo profile with its own event history and list memberships.

Quick reference

---

1. Scheduled / one-off sends (Campaigns)

Klaviyo Campaigns are one-time or scheduled bulk email sends. The audience is defined by selecting up to 15 lists or segments. A seed profile simply needs to be a member of any included list or segment.

Where to add seed addresses

Add the seed profile to one of the lists or segments selected in the campaign's Recipients step. Any included list works. The simplest approach is maintaining a dedicated "Telltide Seeds" list and including it in every campaign's recipients alongside the real audience.

Non-technical path

For CRM and lifecycle managers without API access. Use these UI options inside Klaviyo to add and maintain seed profiles.

Step-by-step: Add a seed profile to a list (Quick Add)

1. Navigate to Audience > Lists & Segments
2. Select the target list (e.g., "Newsletter" or a dedicated "Telltide Seeds" list)
3. Click Quick Add (top right of the list view)
4. Enter the seed's email address in the Email field
5. Check "Profile has granted explicit consent to receive email marketing" to subscribe the profile
6. Optionally add first name, last name, and any other fields used for personalization
7. Click Add subscriber

Step-by-step: Add seed profile via CSV import

1. Navigate to Audience > Lists & Segments
2. Select the target list
3. Click Manage list > Import contacts (some entry points label this Upload contacts)
4. Upload a CSV with columns: Email Address, First Name, Last Name, and any custom property columns
5. When prompted about consent: select Yes, update subscription status for all imported contacts to subscribed
6. Click Next to begin the import

Step-by-step: Add seed via the Klaviyo subscribe page

1. Navigate to Audience > Lists & Segments and open the target list
2. Click Settings on the list, then copy the Subscribe page URL (Klaviyo provides a hosted opt-in page per list)
3. Open the subscribe page in a browser, enter the seed email address, and submit the form
4. Confirm the resulting opt-in email if double opt-in is enabled on that list
5. Verify the seed appears in the list with subscribed consent on the profile's Details tab

This path is useful when the operator cannot create profiles directly but can fill in a hosted form.

Technical path

For email-dev and lifecycle-ops engineers with API key access. All endpoints below use the JSON:API v3 surface and require the revision and Authorization: Klaviyo-API-Key {{private_key}} headers.

Create or update a seed profile

POST https://a.klaviyo.com/api/profiles
revision: 2025-10-15
Authorization: Klaviyo-API-Key {{private_key}}
Content-Type: application/json

{
  "data": {
    "type": "profile",
    "attributes": {
      "email": "seed@example.com",
      "first_name": "Telltide",
      "last_name": "Seed",
      "properties": {
        "Source": "monitoring",
        "Telltide Seed": true
      }
    }
  }
}

For an idempotent upsert (create if missing, update if present), use profile-import instead:

POST https://a.klaviyo.com/api/profile-import
revision: 2025-10-15
Authorization: Klaviyo-API-Key {{private_key}}
Content-Type: application/json

{
  "data": {
    "type": "profile",
    "attributes": {
      "email": "seed@example.com",
      "properties": {
        "Source": "monitoring",
        "Telltide Seed": true
      }
    }
  }
}

Subscribe the seed to a list (sets consent)

POST https://a.klaviyo.com/api/profile-subscription-bulk-create-jobs
revision: 2025-10-15
Authorization: Klaviyo-API-Key {{private_key}}
Content-Type: application/json

{
  "data": {
    "type": "profile-subscription-bulk-create-job",
    "attributes": {
      "profiles": {
        "data": [
          {
            "type": "profile",
            "attributes": {
              "email": "seed@example.com",
              "subscriptions": { "email": { "marketing": { "consent": "SUBSCRIBED" } } }
            }
          }
        ]
      }
    },
    "relationships": {
      "list": { "data": { "type": "list", "id": "<list_id>" } }
    }
  }
}

Klaviyo's Subscribe endpoint does not accept custom properties, so pair this call with a follow-up profile-import to set Source = "monitoring" and any per-account tagging (see the recipe in API options under Section 3). Order matters: subscribe first to set consent, then upsert properties.

Always-on flow coverage

Always-on Klaviyo Flows (welcome series, abandoned cart, browse abandonment, win-back, post-purchase) do not let you attach a recipient list to a single message the way Campaigns do. To make sure the seed is included in every send of these Flows, work at the trigger and filter layer.

1. Add an OR clause to the trigger segment. Open the Flow's Trigger step. If the trigger is a segment, edit the segment definition and add an OR group:

• existing trigger condition, OR
• Properties about someone > Source equals monitoring

This guarantees any profile tagged with Source = monitoring enters the flow alongside genuine triggers. Pair it with the Source custom property set during the Technical path above.

2. For list-trigger flows, subscribe the seed to the trigger list. Welcome series and similar onboarding Flows fire on list addition. Use the Non-technical Quick Add or the Technical profile-subscription-bulk-create-jobs call, targeting the exact list named in the Flow's Trigger step. Profiles already on the list before the Flow was created do not retroactively enter, so the seed must be added (or re-added) after Flow activation.

3. For metric-trigger flows, fire the trigger event for the seed. Abandoned cart, browse abandonment, post-purchase, and win-back Flows fire on metric events such as Started Checkout, Viewed Product, or Placed Order. Send the event for the seed using the Track API:

POST https://a.klaviyo.com/api/events
revision: 2025-10-15
Authorization: Klaviyo-API-Key {{private_key}}
Content-Type: application/json

{
  "data": {
    "type": "event",
    "attributes": {
      "profile": { "email": "seed@example.com" },
      "metric": { "name": "Started Checkout" },
      "properties": { "value": 49.99 }
    }
  }
}

Match the event property keys to whatever the Flow message templates reference (see Section 2 for full payload examples per Flow type). Mismatched keys render empty in the email.

4. Verify via Flow Analytics. Open the Flow, click any message step, and go to Analytics (Last 30 Days) > Recipient Activity. Confirm the seed profile appears under Sent for each step you expect coverage on. If the seed appears under Skipped: Fails Profile Filters or Skipped: Smart Sending, fix the filter or disable Smart Sending on that step (see Section 2).

For dynamic-segment-triggered Flows, also confirm the seed satisfies the segment after any property update. Klaviyo recomputes segment membership near-real-time, so allow a short delay before expecting Flow entry.

Profile attributes required

Seeds need:

• Email address (subscribed status - not suppressed)
• First name if the email uses {{ first_name }} personalization
• Any custom properties referenced in the email content (e.g., birthday, product preferences) - missing values will render as empty or trigger fallback text

Seeds do not need to match any purchase history or behavioral data unless a flow filter or campaign audience filter explicitly requires it.

Ensuring seeds receive the same version as real recipients

A/B subject line tests: Seeds included in the campaign's recipient lists will be randomly assigned to a subject line variant, just like real recipients. They will receive one variant - not all variants. To confirm all variants are delivered, you need one seed per variant or a separate per-variant monitoring send.

Exclusion lists ("Don't send to"): Verify that the seed profile is not a member of any list or segment added to the campaign's Don't send to field.

Gotchas

Smart Sending (Klaviyo's frequency cap): Klaviyo skips any profile that received a message within the Smart Sending window. Defaults differ by channel and are configured independently under Settings > Email/SMS/Push > Sending preferences:

• Email: 16 hours
• SMS: 24 hours
• Push: 24 hours

If a seed received any email in the past 16 hours, Smart Sending will skip it in an email campaign unless disabled.

To disable Smart Sending for a campaign send: open the campaign and go to the Review and send step. Toggle off Skip recently emailed profiles (or Smart Sending, depending on UI version) before scheduling. This is the most common silent-failure cause for monitoring sends, since the toggle is per-campaign and easy to miss.

Global suppression: If the seed profile has been suppressed (hard bounce, manual suppression, or repeated soft bounces), it will not receive the campaign regardless of list membership. Verify suppression status before monitoring. Note: unsubscribes and spam reports flip the profile's consent status to unsubscribed, which also blocks delivery, but they are not stored as suppression reasons.

To check suppression: navigate to Audience > Profiles, search for the seed email, and open the Details tab. The consent indicator shows green (subscribed), red (suppressed), or yellow (neither subscribed nor opted out). Suppression reason, if any, is listed alongside.

Safe Send filter: Klaviyo automatically filters out profiles who have no email subscription status. When adding a seed via Quick Add, always confirm the "granted consent" checkbox is checked.

---

2. Ongoing / automated journeys (Flows)

Klaviyo Flows are triggered automation sequences. The trigger determines when a profile enters the flow. Seed profiles must both satisfy the trigger conditions and pass all flow-level filters.

Flow trigger types

---

Creating trap profiles per journey type

Welcome / onboarding (List trigger)

• Trigger: Profile added to the trigger list (e.g., "Newsletter")
• Seed requirements: Email address, email consent (subscribed status)
• How to trigger: Add the seed profile to the trigger list via Quick Add (Section 1 process). The flow fires immediately on list addition.
• Entry limit: Set the flow's Profile Filter to "Has been in this flow 0 times" if you want to prevent re-sending to seeds. To re-test, remove the seed from the list and re-add it (Klaviyo tracks list addition timestamps).
• Gotcha: Profiles already on the list before the flow was created do not retroactively enter. The flow only fires for new additions.

Abandoned cart (Metric trigger: Started Checkout)

• Trigger: Started Checkout metric (fires when a profile begins checkout in your store)
• Seed requirements: Email address, email consent, a Started Checkout event with cart item properties
• How to trigger: The Started Checkout event is typically tracked via your Shopify or ecommerce integration. For isolated seed testing, send the event directly via the Klaviyo Events API:

POST https://a.klaviyo.com/api/events
revision: 2025-10-15
Authorization: Klaviyo-API-Key {{private_key}}
Content-Type: application/json

{
  "data": {
    "type": "event",
    "attributes": {
      "profile": { "email": "seed@example.com" },
      "metric": { "name": "Started Checkout" },
      "properties": {
        "CheckoutURL": "https://yourstore.com/checkout/token",
        "ItemNames": ["Widget Pro"],
        "Categories": ["Electronics"],
        "Items": [
          {
            "ProductID": "SKU-123",
            "ProductName": "Widget Pro",
            "Quantity": 1,
            "ItemPrice": 49.99,
            "RowTotal": 49.99,
            "ProductURL": "https://yourstore.com/products/widget-pro",
            "ImageURL": "https://yourstore.com/img/widget-pro.jpg",
            "Brand": "Acme"
          }
        ],
        "value": 49.99
      },
      "time": "2026-04-15T10:00:00+00:00"
    }
  }
}

• Critical: The Items array keys must match exactly what your flow email template references (e.g., {{ event.Items.0.ProductName }}). Mismatched keys render as empty in the email.
• Common trigger filter: Flows typically include a trigger filter excluding profiles with a recent Placed Order event. The seed profile won't have purchase history, so it will not be filtered out by this condition.

Browse abandonment (Metric trigger: Viewed Product)

• Trigger: Viewed Product metric
• Seed requirements: Email address, email consent, a Viewed Product event with product properties
• How to trigger: Send the event via the Klaviyo Events API, using the same structure as above but with metric name Viewed Product
• Event properties needed:
• ProductName or Title
• Price
• URL
• ImageURL
• ProductID
• Flow filter to check: Browse abandonment flows typically filter out profiles who placed an order or started checkout after the trigger. The seed profile will pass these filters since it has no purchase history.

Winback / re-engagement (Metric trigger: Placed Order)

• Trigger: Placed Order metric, with a long initial time delay (e.g., 90 days) before the first email
• Seed requirements: Email address, email consent, a Placed Order event in the profile's history that is at least 90 days old
• How to trigger: Send a backdated Placed Order event against the seed profile. Use a time value 91+ days in the past:

"time": "2025-12-01T00:00:00+00:00"

• Key profile filter: Winback flows use a profile filter: "Placed Order zero times since starting this flow." Since the seed won't place another order, it will remain in the flow and receive all emails.
• Gotcha: Klaviyo backdates events in the event history, but the flow still fires from the time the event is received. You cannot retroactively trigger an event 90 days ago and have the flow immediately send the 90-day follow-up. The seed must wait the actual delay duration in real time. To test immediately, temporarily modify the flow's time delay to a few minutes, then restore it.

Post-purchase (Metric trigger: Placed Order)

• Trigger: Placed Order metric, typically with a short delay (e.g., 1 hour, then additional emails at 10 days and 20 days)
• Seed requirements: Email address, email consent, a Placed Order event with order item properties
• Event properties needed:
• Items array (same structure as Started Checkout)
• value (order total)
• OrderId
• How to trigger: Send the Placed Order event via the Klaviyo Events API with current timestamp

Birthday / anniversary (Date Property trigger)

• Trigger: A date property on the profile (e.g., a custom property named Birthday)
• Seed requirements: Email address, email consent, the date property set on the profile
• Date format: YYYY-MM-DD or MM/DD/YYYY. Klaviyo stores dates internally as YYYY-MM-DD.
• How to set: Use the Klaviyo "Create or Update Profile" API endpoint:

POST https://a.klaviyo.com/api/profile-import
revision: 2025-10-15
Authorization: Klaviyo-API-Key {{private_key}}
Content-Type: application/json

{
  "data": {
    "type": "profile",
    "attributes": {
      "email": "seed@example.com",
      "properties": {
        "Birthday": "1990-04-15"
      }
    }
  }
}

• How the trigger fires: Klaviyo evaluates date property triggers daily. The flow fires on the anniversary of the stored date (month and day match). Set the seed's birthday to today's date and the flow fires that same day (or the next daily evaluation).
• Gotcha: The flow fires annually. Re-testing requires either setting the birthday to next year's date or rebuilding the flow with a new test profile.

---

Where to create seed profiles in the Klaviyo UI

1. Audience > Lists & Segments > [Target List] > Quick Add - for subscribing a seed to a list (triggers list-based flows)
2. Audience > Profiles > [search seed email] > Edit profile - for setting custom properties on an existing seed profile
3. Audience > Profiles > Add profile - for creating a new seed profile with initial attributes

For metric-triggered flows, use the Klaviyo API to send events - there is no UI-based event injection tool.

Ensuring seeds progress through the full flow

Two filter types that can block a seed:

1. Trigger filters (evaluated at entry only, for metric-triggered flows): Based on the triggering event's properties. Ensure the event payload matches any trigger filter conditions.
2. Profile filters (evaluated at entry AND before every message): Based on profile-level data. Common blocking conditions for seeds: - "Has been in this flow in the last X days" - if the seed ran through the flow recently - "Is in [specific list/segment]" - if the seed is not a member of a required list - "Has done [metric] zero times" - if the flow requires purchase history the seed doesn't have

To diagnose flow filter blocks:

Two complementary methods, depending on whether you need retroactive or forward analysis:

• Retroactive (why was a profile skipped?): Open the flow message → Analytics (Last 30 Days) → Recipient Activity → expand Other → Skipped: Fails Profile Filters. This shows recently skipped profiles per message and the failing condition.
• Forward (will this seed enter?): Open the flow → Preview mode → pick a specific profile → Klaviyo simulates which steps that profile would hit. For metric-triggered flows, the preview modal is restricted to the 10 most recent profiles. To make a seed appear in the picker, fire a fresh trigger event against the seed first.

Preview-as-profile for personalization checks: Inside any flow message, click Preview and select the seed profile. Klaviyo renders the message against the seed's actual properties, so missing-property issues (e.g., empty {{ first_name }}) surface before the live monitor sees them.

Smart Sending on flow emails: Smart Sending can be enabled or disabled per individual flow email. If a flow email has Smart Sending enabled and the seed received any email in the past 16 hours, that specific email step is skipped. Disable Smart Sending on flow emails during monitoring setup:

1. Open the flow and click the message card
2. In the right-hand sidebar, find the Settings section
3. Toggle Skip recently emailed profiles to off (the toggle is in the sidebar, not behind a gear icon in current UI)

---

How to reset seeds for repeated flow testing

List-triggered flows: Remove the seed from the trigger list, then re-add it. Each re-addition fires the flow if the flow allows re-entry.

Metric-triggered flows: Fire the triggering event again. The flow re-enters if configured to allow re-entry (no "Has been in this flow in the last X days" profile filter blocking it).

Using + subaddressing: Create seed+cycle1@yourdomain.com, seed+cycle2@yourdomain.com as distinct profiles. Each has its own clean event history and can enter flows fresh. All variants deliver to seed@yourdomain.com.

---

3. Platform-specific considerations

API options

All requests should pin a revision header. As of 2026, the current stable revision is 2025-10-15. Klaviyo revisions follow a 2-year lifespan (released → deprecated 1 year later → retired 1 year after that), so update the pin when planning multi-year code paths.

Create or Update Profile (upsert by email):

POST https://a.klaviyo.com/api/profile-import

Creates a new profile or updates an existing one matched by email. Accepts all standard and custom properties.

Subscribe Profile to List:

POST https://a.klaviyo.com/api/profile-subscription-bulk-create-jobs

Subscribes a profile to a list and respects double opt-in settings. Required for list-triggered flow entry.

Add Profile to List (no consent change):

POST https://a.klaviyo.com/api/lists/{id}/relationships/profiles

Adds an already-subscribed profile to a list without changing consent status.

Track Event (fire a metric):

POST https://a.klaviyo.com/api/events

Fires a custom metric event against a profile. Required for metric-triggered flow testing.

Suppress/Unsuppress Profile:

POST https://a.klaviyo.com/api/profile-suppression-bulk-create-jobs
POST https://a.klaviyo.com/api/profile-suppression-bulk-delete-jobs

Note: bulk-delete only removes USER_SUPPRESSED type. Cannot unsuppress HARD_BOUNCE or INVALID_EMAIL.

Authentication: All API v3 calls use Authorization: Klaviyo-API-Key {{private_key}} header. Do not use public API keys for server-side operations.

Recipe — subscribe a seed and set custom properties: Klaviyo's Subscribe endpoint does not accept custom properties, so this is a two-call sequence:

# 1. Subscribe to a list (creates the profile if missing, sets consent)
POST https://a.klaviyo.com/api/profile-subscription-bulk-create-jobs
{
  "data": {
    "type": "profile-subscription-bulk-create-job",
    "attributes": {
      "profiles": {
        "data": [
          {
            "type": "profile",
            "attributes": {
              "email": "seed@example.com",
              "subscriptions": { "email": { "marketing": { "consent": "SUBSCRIBED" } } }
            }
          }
        ]
      }
    },
    "relationships": {
      "list": { "data": { "type": "list", "id": "<list_id>" } }
    }
  }
}

# 2. Set custom properties (e.g., tag the profile as a Telltide seed)
POST https://a.klaviyo.com/api/profile-import
{
  "data": {
    "type": "profile",
    "attributes": {
      "email": "seed@example.com",
      "properties": {
        "Source": "monitoring",
        "Telltide Seed": true
      }
    }
  }
}

Tagging the seed with a Source = "monitoring" property (or similar) makes it easy to exclude from real customer segments and engagement scoring later.

Rate limits and sending caps

Klaviyo publishes explicit per-endpoint rate limits in two windows: a burst limit (per second) and a steady limit (per minute). Limits are tiered per endpoint (XS / S / M / L / XL) and are documented at https://developers.klaviyo.com/en/docs/rate_limits_and_error_handling. The high-volume endpoints relevant to seed monitoring:

• POST /api/events (Track event) — moderate-tier; bursts of seed events can exhaust the per-second budget faster than expected when running multiple monitors in parallel.
• POST /api/profile-import — moderate-tier upsert.
• POST /api/profile-subscription-bulk-create-jobs — bulk endpoint, higher steady limit.

In practice:

• Monitor for 429 Too Many Requests responses
• Read the Retry-After header and implement exponential backoff on 429s
• Smart Sending applies a per-profile cooldown (default 16 hours for email, 24 hours for SMS, 24 hours for push) — seeds will miss flow emails if they received any message in that channel's window

Duplicate contact handling

Email is the primary unique identifier. Klaviyo does not allow two separate profiles with the same email in the same account. Sending a request to create or update a profile with an existing email merges the data into the existing profile.

Use + subaddressing to create genuinely distinct profiles that route to the same inbox: seed+abc@yourdomain.com and seed+def@yourdomain.com are different Klaviyo profiles that both deliver to seed@yourdomain.com.

Platform-specific terminology

Known limitations and workarounds

Two-step process for subscribe + custom properties: Klaviyo's Subscribe endpoint does not accept custom properties. You must (1) subscribe the profile to a list, then (2) update the profile with custom properties in a separate API call. See the recipe under API options above.

Date property triggers fire once daily: You cannot force a birthday flow to trigger immediately by setting a seed's birthday to today - you must wait for Klaviyo's next daily evaluation (timing varies by account timezone and flow settings).

Smart Sending cannot be disabled account-wide: It must be disabled per individual flow email or per campaign send. Check every flow step when setting up monitoring.

Winback flows cannot be tested in real time: The 90-day delay cannot be compressed via API. Test these flows by temporarily reducing the delay to minutes during setup, confirming delivery, then restoring the real delay.

Segment membership is not instant: When you update a profile's attributes that would qualify them for a segment, Klaviyo computes segment membership near-real-time but not instantaneously. For segment-triggered flows, allow a few minutes after updating the profile before expecting flow entry.