Skip to main content
Import contacts in bulk using CSV files. The import process validates numbers, normalizes formats, and handles duplicates automatically.

​
CSV Format

​
Required Column

ColumnDescriptionExample
phone_number or phone or msisdnContact phone number+14155551234 or 4155551234

​
Optional Columns

ColumnDescriptionExample
label_*Any column prefixed with label_ becomes a labellabel_source=facebook
emailEmail address (stored but not used for SMS)[email protected]
first_nameContact first nameJohn
last_nameContact last nameDoe

​
Example CSV

phone_number,label_source,label_campaign,first_name
+14155551234,facebook,summer2024,John
+14155551235,google,summer2024,Jane
4155551236,organic,winter2024,Bob

​
Import Process

1

Prepare Your CSV

Create a CSV file with phone numbers and optional labels. Ensure numbers are valid.
2

Navigate to Sending List

Go to Sending Lists and select the list you want to import to.
3

Click Import

Click the Import Contacts button.
4

Upload File

Drag and drop or browse to select your CSV file.
5

Map Columns

Confirm column mapping. The system auto-detects common column names.
6

Review Preview

Check the preview to ensure data looks correct.
7

Start Import

Click Import to begin processing.

​
Phone Number Normalization

The import process automatically handles various phone number formats:
InputNormalized
4155551234+14155551234
(415) 555-1234+14155551234
415-555-1234+14155551234
+1 415 555 1234+14155551234
14155551234+14155551234
Numbers are assumed to be US (+1) unless they include a country code.

​
Duplicate Handling

When importing contacts that already exist:
ScenarioBehavior
Contact exists on this listLabels are merged (new values override)
Contact exists on different listAdded to this list with specified labels
Contact previously opted-outSkipped (opt-out is permanent)
New contactCreated and subscribed

​
Import Limits

PlanMax Contacts per Import
Starter10,000
Growth100,000
EnterpriseUnlimited
For imports over 100,000 contacts, the process runs in the background. You’ll receive a notification when complete.

​
Import Validation

Each contact is validated during import:

​
Validation Rules

RuleInvalid ExampleResult
Valid phone formatabc123Skipped
Number length415555Skipped
Not a landlineLandline numbersSkipped
Not on blocklistPreviously blockedSkipped

​
Import Report

After import, you receive a report showing: 
Import Complete
---------------
Total rows: 10,000
Imported: 9,523
Skipped (invalid): 234
Skipped (opted-out): 198
Skipped (duplicate): 45

​
Triggering Welcome Journeys

When importing contacts, you can optionally enroll them in a welcome journey.
During import:
  1. Check Enroll in Journey
  2. Select the journey
  3. Imported contacts begin the journey immediately
This is useful for onboarding campaigns where new contacts should receive a specific sequence.

​
Best Practices

Clean your CSV before importing. Remove obviously invalid numbers and test a small batch first.
Establish label naming conventions (e.g., source, campaign, cohort) and use them consistently across imports.
Always include a label_source indicating where contacts came from. This helps with attribution and analysis.
Opted-out contacts cannot be resubscribed via import. This is by design for compliance.

​
Troubleshooting

Large imports can take time to start. Wait a few minutes. If still stuck, check file encoding (use UTF-8).
Check the skip reasons in the report. Common issues: invalid format, numbers already opted-out, landlines.
Ensure label columns are prefixed with label_ (e.g., label_source, not just source).
If numbers are non-US, include the full E.164 format with country code in the CSV.

​
Next Steps

Labels

Organize imported contacts

Audiences

Segment your contacts

Journeys

Automate onboarding