CSV import

Format

Standard CSV. The first row is treated as headers. Email is required; everything else is optional. A minimal file:

email,first_name,last_name
[email protected],Alice,Patel
[email protected],Bob,
[email protected],Carol,Sosa

Recognized columns

• email — required. Lowercased on import.
• first_name, last_name — optional.
• tags — comma- or semicolon-separated. e.g. customer;paid;onboarded.
• status — subscribed | unsubscribed (defaults to subscribed).
• custom_field.<name> — anything else; columns matching this pattern get stored in the contact's custom_fields JSON.

Steps

1. Contacts → Import → drop or pick a CSV.
2. Preview the column mapping. Maillayer auto-detects standard names; remap any that don't match.
3. Optionally apply a tag to every row in this batch (e.g.imported-2026-04-29).
4. Click Import. The upsert is idempotent by email — re-importing the same file updates rather than duplicating.

What gets updated vs created

• New email: contact created with all CSV fields.
• Existing email: empty CSV fields are skipped (don't overwrite). Non-empty fields update.
• Tags: added, never removed. Existing tags survive.
• status: only set on create or when explicitly present.