Import contacts

Register contacts for email, SMS, WhatsApp, and Viber from one CSV file. One phone number column can register a contact for both SMS and WhatsApp, so you don’t need a separate file per channel.

Prepare your CSV file

File format

• The first row must contain column headers describing the data in each column.
• Each subsequent row represents a single contact, with values corresponding to the headers.
• Values must be separated by commas.
• Save the file in UTF-8 encoding to ensure proper character display.
• The maximum file size is 100 MB.

Contact columns

Include at least one of these columns, depending on the channels you want to register contacts for:

• Email: the recipient’s email address.
• Phone number (for SMS, WhatsApp, and Viber): in international format, starting with + and the country code, for example +120XXXXX234. Enter the plain number without a whatsapp: or viber: prefix. Pushwoosh adds the prefix when you map the column to that channel.

If a phone number isn’t in a valid international format, it’s skipped for that channel. The rest of the row still imports.

Note

The column names in your CSV file don’t need to match these labels. During import, you map your existing column names to a channel in the wizard. For example, a column named Mobile can be mapped to the SMS or WhatsApp channel.

Optional columns

• User ID: a unique identifier for the user (e.g. name or email). Not required, but recommended so the contact’s channels share one user profile instead of several.
• Any other column can be mapped to a system tag for segmentation and personalization, for example Location, Birthday, Language, or Customer type.

Example CSV file

Email,Mobile,User ID,Name,Location
john.smith@email.com,+120XXXXX234,john.smith@email.com,John Smith,New York
jane.smith@email.com,+131XXXXX890,jane.smith@email.com,Jane Smith,Los Angeles

Upload and map the CSV file

1. Go to Audience → Import CSV → Import Contacts.

   

2. Click Upload CSV and select your file. To replace it, click Upload Another CSV.

   Caution

   Pushwoosh checks the whole file when you upload it. A row that can’t be parsed (its column count doesn’t match the header, or a quoted value isn’t closed) gets the file rejected right away. A toast names the row and the reason, for example “Row 42: the number of values does not match the header.” Nothing is imported in this case. Fix that row and upload the file again.

3. Enter a Segment name for the imported contacts.

4. Under Contact column in CSV, select a column and, next to it, choose the Channel it registers (Email, SMS, WhatsApp, or Viber). Click + Add channel to map another column, or to map the same column to an additional channel.

5. Under UserId column in CSV, select the column with unique user identifiers, if your file has one.

6. To include extra data for segmentation, select a Column Name from your CSV and assign it a Tag. Click + Add Column to map more attributes.

   

7. Click Start Import.

   Caution

   If Pushwoosh can’t check the email addresses when the import starts, the import stops before any row is imported. An Import failed toast says “Email addresses could not be checked because the validation service is unavailable. Try again later.” The wizard returns to the upload step, so upload the file and map the columns again a bit later.

   Pushwoosh checks addresses in batches of up to 1,000 rows. If the check becomes unavailable partway through a large file, the import also fails, but the rows processed before that point stay imported.

After the import, the contacts are available for campaigns on the channels you mapped. They appear as a new segment in the Segments list and can also be accessed via User explorer.

The completion screen shows two counts:

• Created: channel registrations that are new to the app.
• Updated: channel registrations that already existed, including when the same address or number re-registers under a different User ID or on a different device platform.

Both count channel registrations, not contacts or CSV rows. A contact mapped to two channels, for example SMS and WhatsApp, adds 2.

For an updated contact, only the tags mapped in step 6 change. Their values are overwritten with the CSV values. Other tags already set on the contact stay as they are.

Note

Older imports in the recent imports list show a single Imported count instead of Created and Updated.

Rows skipped during import

Pushwoosh checks every email address in the file by the same rules as an email subscription made through your website, the SDK, or the API. An address is skipped if it’s malformed, belongs to a disposable email service, or is on your account’s bounce list.

The completion screen groups skipped rows by reason:

• Email address is not valid
• Disposable email address
• Email address is in the bounce list
• Phone number is not valid
• No contact address in the row: every mapped column was empty

A row can be partially imported and still show up in this breakdown. For example, the phone column imports, but the email address in the same row is skipped as disposable.

Click Download skipped rows to get a CSV of those rows only. The file adds the skip reason as an extra column so you can fix the rows and re-upload them.

Note

Download the file before you leave the completion screen. If you open the same import later from the recent imports list on the Import CSV hub, you see the reason counts but no download link.

Email addresses on domains without a mail server

After the import, Pushwoosh checks in the background that the domain of each imported email address has a mail server. If the domain doesn’t exist or doesn’t accept mail, the address is unsubscribed from email. If the domain can’t be checked, for example because DNS doesn’t respond, the address stays subscribed.

Pushwoosh doesn’t check whether a specific mailbox exists on a working domain.

Rows the import failed to register

Some rows pass the skip checks and are still rejected when Pushwoosh registers them. For example, a phone number in a valid format is rejected for SMS if it isn’t a mobile number. Pushwoosh counts rows like this as Failed, separately from Created, Updated, or Skipped.

Failed rows aren’t broken down by reason and aren’t included in the skipped-rows download. To find them, compare your source CSV with the imported segment. Check the missing contacts, for example replace a landline number with a mobile one, and re-upload only those rows in a new import. If a row fails again and you can’t see why, contact Pushwoosh Support.