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 preference, 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 in, and both end in the same CSV import:

• A regular CSV can map a column to a channel's marketing-preference attribute, the same as any other attribute.
• Upload marketing preferences opens a page dedicated to consent imports. It lists the consent attributes under Available attributes, and under Resources it offers Download opt-out template and the Opt-out import guide, which leads back to this section. Its Upload CSV button then takes you into the same wizard.

What a consent import can and can't set:

• The marketing preference, one column per channel. The upload page lists _accepts_marketing_sms as Accepts marketing (SMS/RCS), plus _accepts_marketing_email and _accepts_marketing_whatsapp. The SMS column also governs RCS: RCS has no consent attributes or columns of its own (see Shared consent).
• Not suppression. A CSV import can't suppress a contact: an _is_subscribed_* column in the file is not applied, and the contact's suppression doesn't change. Suppression is set from the contact's profile or through the API (see How consent works).

The values are true / false, and an empty cell means "no change": it leaves the contact's existing value untouched rather than resetting it. A contact who gets no value at all keeps the default, no preference (null).

The opt-out template

A list of contacts who don't want your promotions, for example people who complained, is a marketing opt-out. Download opt-out template gives you a ready file for it, marketing_opt_outs.csv, comma-separated, with four columns:

• _phone_mobile: the contact's mobile number, in international format.
• _email: optional; it helps match contacts you already have.
• _accepts_marketing_sms: the SMS preference, which also covers RCS.
• _accepts_marketing_whatsapp: the WhatsApp preference.

The example rows hold only false or an empty cell: false records the opt-out on that channel, and an empty cell leaves that channel as it is. Replace them with your own list. If you only have the opt-outs, upload them in a separate CSV with the preference set to false, and use Mobile phone and Email as merge attributes so the rows match existing contacts.

Making sure the opt-outs are respected

Imported opt-outs only apply to sends under the No opt-out or Opt-in policy. Basic ignores marketing preferences, so it still reaches them: it only skips suppressed contacts. To respect them by default, choose No opt-out as the default policy in each channel's Compliance tab. RCS has its own policy, and so does WhatsApp, so setting it on SMS doesn't cover them. The upload page links to the settings of each channel available in your project (SMS settings, RCS settings, WhatsApp settings); the policy is in the Compliance tab there. More in If you import opt-out lists, and in Compliance policies for what each policy reaches.

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