When uploading CSV files to add contacts to your Marketing plan, you may experience an error or partial upload of contacts. We will send a confirmation of contact uploads to the admin email address on file as well as any email addresses that are included within the "Marketing" > "Notifications" menu. You can add up to 10 additional addresses per account.
The email will contain the following information:
- Processed (total number of unique contacts read in the CSV file)
- New (number of new contacts that did not previously exist in any list on your account)
- Updated (number of contacts that already existed on the account but were updated)
- Errors (number of contacts that failed to upload due to an error)
When errors are logged in an upload, that email will include a blue button under this information:
"Download Detailed Error File". This file will include the email addresses and error reasons.
The most common issue we see with uploading contacts via CSV (Comma Separated Values) file is an error with the content of the file. We frequently see values in files separated by a semicolon ; - rather than the correct comma ,.
Even in files with proper formatting (CSV), the software used to create the file or different regional/language options, could produce a file with values separated by semicolons.
If your CSV file doesn't upload as anticipated, we recommend checking the file in a text editor to make sure it's not using semicolons for separating values.
- Open with your preferred text editor.
- Use the Find and Replace option to search for
;. - Replace all semicolons with
,. - Save the file as a .csv.
Formatting Rules
Follow the rules below when formatting a CSV to upload into Marketing Campaigns. Click here to download a sample CSV like the one shown below:
Contact Info
Your CSV should contain the following information about each contact:
- email (required)
- first_name
- last_name
In addition to email, first_name, and last_name, there are also several other reserved fields such as city and zipcode. You can also include custom fields with additional identifying information for each contact in the CSV. For example, you could specify birthday, occupation, and age as the custom fields. The data in the custom fields are critical for both segmentation and content personalization.
Header Row
The first row of your CSV must be a header row containing labels identifying each column. Headers should only use letters, numbers, and underscores. Header fields can be blank in your CSV, but must be named and have their type defined later during the upload process.
You cannot use spaces, dashes, or other special characters, except for underscores in a CSV.
If you add custom field data to your CSV, you can save some time when uploading by naming the columns the same as the custom fields you have previously defined.
SendGrid identifies individual contacts by their email address, so one of the CSV headers must be email. If you do not include the email column, SendGrid will not add any information to your contact database or list. Rows in your CSV without an email address in the email column will automatically fail to add to your contact list, but they will not cause the entire upload to fail.
Character Encoding
If your contacts list has non-English characters, please make sure that you are UTF-8 encoding your CSV file.
Removing invalid and duplicate addresses
SendGrid removes duplicate and invalid email addresses including email addresses with any special characters except for underscores from your list during upload, so the number of contacts can potentially change between your CSV and your Marketing Campaigns list.
Custom Field Data Types
You can create three different types of custom fields, based on the data type. Each data type will allow you to use different queries for segmentation:
- Date - allows you to select contacts before, after, or on a specific date. Example: 1/1/2014
- Text - allows you to select contacts who match the specific text. Example: Pet field that says "Dog"
- Number - allows you to do things like “greater than,” “less than,” or “equals” a specific number. Both decimal and integer values are accepted. Example: The age of your recipient: 27
Date Formatting
Properly format any dates in your CSV. If you create your CSV with Excel and it is not displaying correctly, change the date format to display appropriately before exporting to CSV. Use one of the following date formats: MM/DD/YYYY, MM/D/YYYY, M/D/YYYY, or M/DD/YYYY.
Text
Format your text fields so that there are no strings of numbers that appear like phone numbers, zip codes, and so on. They should not contain punctuation characters like a dash, underscore, parenthesis, or multiple dots.
- US Zip Code: 80202-1713
- Phone numbers: "(555) 555-5555" or "555.555.5555"
- Monetary Values with the currency indicator such as $3.50 or €5.73
Numbers
Number type fields can only include digits or a decimal (0,1,2,3,4,5,6,7,8,9,.). No other characters are allowed. If you use Number formatting for phone numbers for example, they cannot include characters such as:
"(", ")", or "-"
A number type field with the following data would case an error in the upload: (303)555-1235
Float type conversion error.
- Categorize dashes or decimal places that are past the hundredth place as text_fields (-100, 123.123 are text fields, 100, 12.12 can be number fields).
- Number fields can include monetary values without the currency symbols. For example, 19.95 would be a number field, and $19.95, including the ($), would be a text field.
- As you are uploading your CSV, make sure you select the correct fields for your Field type.
Troubleshooting
Below are a few errors you may encounter when uploading a CSV to Marketing Campaigns, along with tips to correct the root issue.
We were unable to detect an email column in the CSV file headers. The email column must always have a header of "email".
- If there is a header labeled "email" try moving it to column A, so it is the first header in your list.
- Your CSV must include a column named "email".
Some of your custom fields have not been selected.
- Look for hidden characters in your CSV file if you have worked with the file multiple times and made some adjustments to the data.
- A common fix for this error would be to select all and copy your data to a new CSV spreadsheet. This should remove any hidden characters.
Each custom field can only be applied to a column once. Please check your columns and try again.
- Check your CSV for duplicate fields, especially fields that have matching information as your
email,first_nameandlast_namefields. You cannot edit these field names as they are reserved. - For example, if you have a "Name" field, it may conflict with your
first_namereserved field.
We were unable to detect any headers in your CSV file.
- Include headers at the top of each column. All CSV uploads must contain the "email" header. Header fields can be blank in your CSV but must be defined later during the upload process.
