Add List Members

Push / DestinationList Management

Overview

The Add List Members action allows you to add or update subscribers in Klaviyo lists. This action performs an upsert operation—if the email already exists in the list, the profile will be updated; if it doesn't exist, a new member will be added.

This is the primary action for syncing customers, subscribers, or contacts from other systems into Klaviyo for email marketing campaigns, automation workflows, and customer segmentation.

Key Features

🔄 Upsert Operation

Automatically creates new members or updates existing ones based on email address

📧 Email & Phone Support

Sync both email addresses and phone numbers for multi-channel marketing

🎯 Profile Updates

Update customer profiles with latest information from your source systems

📊 Batch Processing

Efficiently add multiple members in bulk operations

Configuration

Required Fields

Ensure your Klaviyo integration is configured with valid credentials:

{
  "klaviyo": {
    "api_key": "pk_8eef70f5c90d76f5ecd2c10487b7f9c402",
    "list_id": "KKbLLU"
  }
}

🔑 Configuration Requirements

api_key: Your Klaviyo Private API Key (starts with pk_)
list_id: The ID of the Klaviyo list to add members to

Field Mapping

Map your source system fields to Klaviyo's required format:

{
  "mapped_fields": [
    {
      "origin_field": "Email1",
      "destination_field": "email",
      "convert_function": ""
    },
    {
      "origin_field": "PhoneNumber1",
      "destination_field": "phone_number",
      "convert_function": ""
    }
  ]
}

Field Specifications

email

Required

Type: String

Description: The subscriber's email address

Validation: Must be valid email format (user@domain.com)

Notes: Primary identifier for list members. Used for deduplication and profile matching.

phone_number

Optional

Type: String

Description: The subscriber's phone number

Format: Include country code for best results (e.g., +1234567890)

Notes: Enables SMS marketing capabilities in Klaviyo. Can be used for multi-channel campaigns.

💡 Mapping Tips

Email field is mandatory—workflow will fail without valid email addresses
Phone numbers should include country codes for international compatibility
Use convert_function for data transformation (e.g., lowercase emails, format phone numbers)
You can add custom properties beyond email and phone by extending the mapping

Workflow Configuration

Example workflow configuration for adding list members:

{
  "name": "Sync Customers to Klaviyo",
  "origin": {
    "microservice": "customer",
    "action": "pull_customers"
  },
  "destination": {
    "microservice": "integrations",
    "action": "list_member_add",
    "type": "push",
    "chunk_size": 100,
    "chunk_waiting_time": 2000,
    "integration": {
      "name": "klaviyo"
    },
    "mapped_fields": [
      {
        "origin_field": "email",
        "destination_field": "email"
      },
      {
        "origin_field": "phone",
        "destination_field": "phone_number"
      }
    ]
  }
}

Workflow Parameters

action: Set to list_member_add
type: Set to push (destination operation)
chunk_size: Number of records to process per batch (50-200 recommended)
chunk_waiting_time: Delay between batches in milliseconds (1000-3000 recommended)
mapped_fields: Array of field mappings from origin to destination

Use Cases

🛒 E-commerce Customer Sync

Scenario: Automatically add customers to Klaviyo when they make purchases or create accounts in your e-commerce platform.

Benefit: Build customer segments for targeted campaigns, abandoned cart recovery, and post-purchase follow-ups.

📝 Newsletter Signups

Scenario: Sync website newsletter subscription forms to Klaviyo lists.

Benefit: Centralize all email subscribers in Klaviyo for unified campaign management and automation.

🔄 CRM to Klaviyo Sync

Scenario: Keep Klaviyo lists synchronized with your CRM system's contact database.

Benefit: Maintain consistent customer data across platforms for coordinated marketing efforts.

🎯 Event-Based List Building

Scenario: Add users to specific lists based on actions (webinar registration, product interest, etc.).

Benefit: Create highly targeted segments for behavior-based email campaigns.

📊 Multi-Source Aggregation

Scenario: Collect contacts from multiple touchpoints (website, POS, mobile app) into unified Klaviyo lists.

Benefit: Build comprehensive customer profiles with omnichannel marketing data.

⚡ Real-Time Subscription

Scenario: Instantly add new leads to Klaviyo as they sign up across your digital properties.

Benefit: Trigger immediate welcome emails and onboarding sequences for new subscribers.

Behavior & Logic

Upsert Operation

This action performs an upsert (update or insert) based on the email address:

1. Email Check

Klaviyo checks if the email address already exists in the specified list.

↓

2. If Email Exists

The existing profile is updated with new information (phone number, custom properties).

↓

3. If Email Doesn't Exist

A new member is created in the list with the provided data.

↓

4. Result

Member is successfully added or updated in the Klaviyo list.

📝 Important Notes

Email is the unique identifier—duplicate emails will update existing profiles
Updates are partial—only provided fields are changed (existing data is preserved)
If phone number changes, the new value replaces the old one
Profile properties merge with existing data rather than overwriting entire profile

Compliance & Best Practices

⚠️ Email Marketing Compliance

Legal Requirement: Only add contacts who have explicitly opted in to receive marketing communications. Adding users without consent violates CAN-SPAM (US), GDPR (EU), CASL (Canada), and other email marketing laws.

✅ Best Practices

Verify consent: Ensure all contacts have opted in before adding to lists
Double opt-in: Consider using Klaviyo's double opt-in feature for email verification
Source tracking: Track where each subscriber came from for audit purposes
Clean data: Validate email addresses before sending to avoid bounces
Batch operations: Use appropriate chunk sizes to respect API rate limits
Error handling: Implement retry logic for failed additions
Data quality: Remove duplicates and invalid emails at the source
Unsubscribe syncing: Also implement removal workflows for unsubscribes

🔒 Data Privacy

When syncing customer data to Klaviyo:

Only transfer necessary fields (avoid sending sensitive information)
Ensure your data processing complies with GDPR, CCPA, and applicable regulations
Maintain records of consent and data processing activities
Implement data retention policies consistent with your privacy policy

Performance Optimization

⚡ Batch Size Tuning

Optimize chunk_size based on your needs:

Small batches (10-50): Better for real-time syncing, lower memory usage
Medium batches (50-200): Balanced approach for most use cases
Large batches (200-500): Faster bulk imports, higher memory usage

⏱️ Rate Limit Management

Avoid rate limit errors with proper timing:

Set chunk_waiting_time to 1000-3000ms for large imports
Monitor API response times and adjust delays accordingly
Implement exponential backoff for retry logic
Schedule large imports during off-peak hours

🎯 Incremental Syncing

For ongoing synchronization:

Track last sync timestamp to only process new/updated records
Use filters in origin query to reduce data volume
Schedule regular small syncs rather than infrequent large ones

Troubleshooting

🔴 Issue: "Invalid email address"

Cause: Email format doesn't meet Klaviyo's validation requirements.

Solution: Validate emails before sending. Remove spaces, ensure proper format (user@domain.com), and check for special characters.

🔴 Issue: "Rate limit exceeded"

Cause: Too many API requests in a short time period.

Solution: Increase chunk_waiting_time (try 2000-3000ms), reduce chunk_size, or spread imports over longer time periods.

🔴 Issue: "List not found"

Cause: list_id is incorrect or list was deleted.

Solution: Verify list_id in Klaviyo Lists → Settings. Check that list still exists and ID is correct (case-sensitive).

🔴 Issue: "Authentication failed"

Cause: API key is invalid, expired, or lacks required permissions.

Solution: Verify api_key is a Private API Key (starts with pk_). Check permissions in Klaviyo settings include list management access.

🔴 Issue: "Members not appearing in list"

Cause: Klaviyo may take a few minutes to process and display new members.

Solution: Wait 5-10 minutes and refresh the list view. Check workflow logs for API response confirmation. Verify no validation errors occurred.

🔴 Issue: "Phone number not saved"

Cause: Phone number format is invalid or missing country code.

Solution: Include country code (e.g., +1 for US). Use E.164 format: +[country code][number]. Remove spaces, dashes, and parentheses.

API Response

Success Response

When members are successfully added, Klaviyo returns confirmation:

{
  "status": "success",
  "members_added": 100,
  "members_updated": 25,
  "list_id": "KKbLLU"
}

Error Response

If an error occurs, you'll receive details about what went wrong:

{
  "status": "error",
  "message": "Invalid email address",
  "details": {
    "email": "invalid-email",
    "reason": "Email format validation failed"
  }
}