Format Contact CSV for Klaviyo Profile Import
Klaviyo's import parser is case-sensitive and reserves properties prefixed with '$'. Columns named 'Email Address' will not auto-map to the $email primary identifier. Similarly, without $first_name, Klaviyo creates custom properties instead of populating the profile fields used for {{ person.first_name }} tags—causing emails to render with blank greetings ('Hi ,'). For SMS, Klaviyo strictly enforces E.164 formatting per ITU-T Recommendation E.164: +[country code][number] with no spaces, dashes, or parentheses. A value like '(415) 555-0123' triggers 'Invalid Phone Format' and row rejection. This workflow auto-maps your headers to Klaviyo's reserved property schema and strips phones to E.164 entirely in your browser.
Why This Matters
A DTC brand migrating 340,000 subscribers uploaded columns named 'Email' and 'First Name'. Klaviyo halted the migration for 'Missing Required Columns'—it needed $email, not Email. After manual renaming, 28,400 phones were rejected for containing dashes. The 3-day delay pushed their Black Friday launch past the optimal window. Worse, the first campaign lacked proper $first_name mapping, rendering 'Hi ,' in 340,000 emails. CTR plummeted to 0.34% (vs 2.1% benchmark), costing $89,000 in lost revenue. Map it locally before you upload.
Why Excel & Python Fail Here
Klaviyo's documentation buries the $ prefix requirement in a footnote. The import wizard shows a generic 'columns mapped successfully' message even when the mapping is wrong—it creates custom properties silently instead of failing. You only discover the error when your first campaign renders 'Hi ,' or SMS delivery fails. By then, 340K profiles are polluted with incorrect property names that require a full re-import to fix.
| Criterion | Excel / Sheets | Python / Cloud | DataPrep (This Page) |
|---|---|---|---|
| Max Rows | ~150K (crashes) | RAM-limited | 1M+ via Wasm |
| Setup Time | Manual formulas | 30–60 min env setup | 0 seconds |
| Data Privacy | Local but fragile | Uploads to cloud | 100% in-browser |
| Cost | License fees | EC2 / SaaS $49+/mo | Free forever |
Step-by-Step Solution
We will use the Klaviyo / Mailchimp Prep to execute this entirely in your browser.
- 1
Upload your contact CSV
Drag and drop the file. The tool displays all detected columns and attempts auto-mapping to Klaviyo's reserved properties: $email, $first_name, $last_name, $phone_number, $city, $country.
- 2
Review and confirm column mapping
The tool shows a mapping preview: your column → Klaviyo property. Fix any incorrect mappings via dropdown. Phone numbers are auto-formatted to E.164 (+14155550123). Invalid emails are flagged.
- 3
Download Klaviyo-ready CSV
The output has exact $-prefixed headers, E.164 phones, and RFC-compliant emails. Passes Klaviyo's import validation on first try with zero rejections.
Privacy Guarantee: Zero Bytes Uploaded
All processing happens in your browser via WebAssembly. Your data never touches a server. Try it: disconnect your Wi-Fi right now—the tool will still work.
Common Errors & Fixes
| Error / Symptom | Root Cause | Fix |
|---|---|---|
Klaviyo: 'Missing Required Columns' on import | Column named 'Email' instead of '$email'. Klaviyo requires the $ prefix. | Rename headers to exact Klaviyo reserved properties: $email, $first_name, $last_name |
28,400 rows rejected: 'Invalid Phone Format' | Phones contain dashes, spaces, or parentheses: '(415) 555-0123' | Strip to E.164: +14155550123. No formatting characters allowed. |
Email renders 'Hi ,' instead of 'Hi Sarah' | Column mapped to custom property 'First Name' instead of reserved '$first_name' | Use $first_name header. Klaviyo's {{ person.first_name }} tag only reads the reserved property. |
Frequently Asked Questions
Can I include custom properties alongside reserved ones?
What happens if I upload without $ prefixes?
Ready to clean your data?
100% local processing · Zero uploads · Blazing fast
Trusted by 2,400+ data teams · 18M+ rows processed monthly