CSV & copy-paste import

Uploading a CSV or pasting rows from a spreadsheet is the manual way to bring contacts into a project. Both run through the same import wizard and produce a data source you can refresh later. This page covers the file format, the wizard steps, updating an existing import, and — important — how to set each contact's marketing consent as you import.

CSV file format

A few rules keep an import clean:

Requirement	Detail
File size	Up to 20 MB
Encoding	UTF-8 (auto-detected; a warning shows if the file isn't UTF-8)
Separator	Auto-detected (the template uses ;)
First row	Column headers
Phone numbers	International format, mapped to _phone_mobile with a Default country picker

The wizard auto-detects the encoding and separator, so in most cases you only have to confirm. Phone numbers map to the _phone_mobile attribute; if some rows lack a country prefix, the Default country picker fills it in.

Row counts are a warning, not a hard limit: at 100,000 or more rows in a file (or 5,000 in a paste) the panel flags the size, but the import can still run.

The import wizard

The wizard walks through up to five steps, some skipped automatically when they don't apply:

1. 1

   Upload

   Choose the .csv file. The panel parses it, detects encoding and separator, and previews the rows.

2. 2

   Mapping

   Map each column to an Instasent attribute — match an existing one, create a new attribute, or ignore the column. See field mapping.

3. 3

   Key field

   Pick the identifier that decides who is who. Skipped if the project isn't active yet.

4. 4

   Merge

   Resolve duplicates. Shown only when email or phone aren't unique in your data.

5. 5

   Tags

   Add at least one tag to finish; the tags label the contacts this import brings in.

Invalid rows are surfaced as warnings with a preview, not rejected outright — you see what's wrong and decide whether to proceed.

Updating an existing import

To refresh a previous CSV import, re-upload a file with the same key field and mapped fields. This update wizard has three steps — select the source, upload the new file, and configure the update:

• Update existing — contacts already present are updated. Always on.
• Create new — contacts not seen before are added. Always on.
• Delete absent — a toggle (off by default). When on, contacts missing from the new file are removed from the source.

You can keep existing tags or add new ones (up to 38 characters each).

Copy and paste

Copy and paste uses the same wizard, but instead of a file you paste delimited text (from Excel or a CSV) into a text area. The first row is the headers, just like a file. The limit is 10,000 lines, and the source is named copy-paste-YYYY-MM-DD.HH-mm by default.

Importing consent

An import can set each contact's marketing consent, not just their attributes — and getting this right is essential, because an import can otherwise overwrite a contact's real preference.

There are two ways to bring consent in:

• A regular CSV can map columns to the consent attributes directly, the same as any other attribute.
• The dedicated marketing-preferences flow is a purpose-built import for consent state. Its template (unsubscribed_users.csv) has the columns _phone_mobile, _email, _is_subscribed_sms, _accepts_marketing_sms and the matching _email, _rcs and _whatsapp variants.

In both cases the values are true / false, and an empty cell means "no change" — it leaves the contact's existing value untouched rather than resetting it. When a column isn't provided at all, the defaults apply: _accepts_marketing_* defaults to no preference (null) and _is_subscribed_* defaults to subscribed (true).

For what each consent attribute means and how the values combine, see Subscription attributes.