Importing Contacts CSV — Best Practices and the 6-Click Field Mapping Wizard

For large lists or ongoing-sync scenarios, the CSV-through-UI path is one tool among several.

Bulk update via re-import:

If you need to update a single field across thousands of subscribers (e.g. reset everyone's frequency to weekly), the easiest path:

1. Export the list to CSV (Audience → list → Export → All fields)
2. Open in spreadsheet, edit the column for the values you want
3. Re-import with duplicate handling = Update

AcelleMail processes the file in 5-30 minutes depending on size. The advantage over API is no scripting required; the downside is no per-row tracking of which value changed.

Scripted update via API (when you need fine control):

ACELLE_TOKEN="..."

# Set everyone's 'frequency' to 'weekly' in one list:
curl -X POST "https://acellemail.com/api/v1/lists/{list_uid}/subscribers/bulk-update" \
  -H "Authorization: Bearer $ACELLE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {"status": "subscribed"},
    "updates": {"fields": {"frequency": "weekly"}}
  }'

Returns {updated_count, failed_count} synchronously. Handle 429 with backoff for large updates.

Idempotent CSV import pipeline:

When syncing from a CRM nightly, the standard pattern is:

# 1. Export CRM contacts to CSV
crm-export --tag=marketing --output=/tmp/contacts.csv

# 2. Pre-validate (optional but recommended)
csvkit validate /tmp/contacts.csv

# 3. Upload to AcelleMail
curl -X POST "https://acellemail.com/api/v1/lists/{list_uid}/imports" \
  -H "Authorization: Bearer $ACELLE_TOKEN" \
  -F "file=@/tmp/contacts.csv" \
  -F "duplicate_handling=update" \
  -F "field_mapping={\"email\":\"email\",\"first_name\":\"first_name\"}"

# 4. Poll for completion + result
import_uid="..."  # from response
curl -H "Authorization: Bearer $ACELLE_TOKEN" \
  "https://acellemail.com/api/v1/imports/$import_uid"

The full audit trail (which rows were updated, which were skipped, which failed) is in the response JSON.

Resumable imports for very large files:

For files >100k rows, the wizard can run for 15+ minutes. If the queue worker is restarted mid-import, AcelleMail's import job is designed to resume from the last completed batch — no rows are double-processed. The audit trail shows the exact row offset where the resume happened.

Pre-import deduplication:

If your CSV has internal duplicates (same email twice within the file), AcelleMail processes the rows in order and the LAST row's values win for the duplicate. To control which row wins, sort the CSV in your spreadsheet first — most recent record last.

For server-side dedup, use the API in a loop with upsert: true and last_updated_at field comparison.

Recovery from a bad import:

If you imported with wrong field mapping (e.g. mapped first_name to email and now have garbage), the recovery path:

1. Don't panic — the original data is still there in your spreadsheet
2. AcelleMail keeps per-import audit logs (admin → Audit log → filter by import event)
3. Bulk-update the affected field back to correct values via API or re-import

There's no automatic "undo last import" — recovery is always forward-looking. Always test with a 10-row sample first on a non-critical list before running a 100k import.

Field type changes:

If you've imported 100k subscribers with birthday as a Text field, then realize you want it as a Date field — the change is in two steps:

1. Audience → list → Fields → edit birthday → change type Text → Date. AcelleMail re-validates all existing values; rows where the value doesn't parse remain as-is until you fix them.
2. Either bulk-update the bad rows via API, or export → fix in spreadsheet → re-import.

Custom-field discovery during import:

If your CSV has a column AcelleMail doesn't know about (e.g. lifetime_value and the list doesn't have that field yet), the field-mapping step in the wizard offers Create new field on import. Pick the field type (Number / Text / Date) → AcelleMail creates the field on the list + maps the column to it in one click. Useful for one-time migrations from systems with custom schemas.

Compliance audit trail:

Every import is logged with:

• Who triggered it (admin user ID)
• When (timestamp)
• Which file (filename + hash)
• How many rows added / updated / skipped / errored
• The full error CSV is retained 90 days (configurable in admin settings)

For GDPR audit requests ("show me when you obtained this subscriber's consent"), the import audit log answers it — the import row references the original CSV which presumably has the source/opt-in date column.