CSV Upload & Format

What it is

CSV upload lets you populate a mailing list from a spreadsheet or Excel file. You match the columns in your file to the fields thanks.io expects, verify a sample of the rows, and import.

How to upload a CSV

1. Open Mailing Lists in the sidebar and open the list you want to fill. For a new list, click Add Mailing List, enter a List name, and click Create list first.
2. Click Add recipients, then choose Upload Mailing or Email CSV.
3. If the dialog asks you to name a new list (as it does before you have any lists), enter one; a name is suggested from your file.
4. Click Choose a file and select your .csv, .xlsx, or .xls file. The column names must be in the first row.
5. Optionally tick a paid lookup under Paid data lookups (optional) - see below.
6. Click Upload and match columns.
7. Match your columns: for each column in your file, the first row's value is shown beside a field dropdown. Pick the field each column holds, or Skip it. Messages above the table tell you what still needs fixing (for example "Map a column to Address."). Click Verify data.
8. Verify your data: review the first rows as they'll be imported, after address verification. Each row is marked as readable, to be looked up from its email, or skipped, with a count of the rows that have a mailing address. Click Back to change a column.
9. Click Import N rows. The list fills in as the rows are processed.

After import, thanks.io validates addresses. Undeliverable addresses are flagged with a warning; switch on Undeliverable only on the list to see them.

Column reference

The column mapping step lets you match any CSV header to the correct field - your column names don't need to match the field names below.

Required field

The mapper blocks submission until the Address field is mapped.

Field	Description
address	Street address, or the full address (street, city, state, zip) in a single column

If your address column contains only the street (not a full address), also map these:

Field	Description
city	City
province	State or province abbreviation (e.g., CA, NY)
postal_code	ZIP or postal code

Name fields

Field	Description
name	Full name in a single column
firstname	First name
lastname	Last name

Optional fields

Field	Description
address2	Apartment, suite, unit number
company	Company or organization name (also used for spouse name)
country	Country
email	Email address
phone	Phone number
dob	Date of birth - required for Birthday campaigns. Format: MM/DD or MM/DD/YYYY
anniversary	Anniversary date (e.g., house anniversary)
custom1 - custom10	Custom fields; accessible via %CUSTOM1%-%CUSTOM10% in messages and ~CUSTOM1~-~CUSTOM10~ in front designs

Absentee (Subject) fields

Use these when your list targets absentee property owners - the mail goes to the owner's mailing address but references a separate property address.

Field	Description
absentee_address	Absentee property street address (or full address)
absentee_city	Absentee property city
absentee_state	Absentee property state / province
absentee_postal_code	Absentee property ZIP / postal code

Note: Absentee fields use Custom 1 and Custom 2, so those can't be mapped as well.

Paid data lookups (optional)

The upload step has two optional, pay-per-use lookups. Neither runs unless you tick it, and both are locked until a card is on file (or while your credit balance is negative).

• Find mailing addresses from emails - for rows with an email but no street address, thanks.io looks up the mailing address. 7¢ per address found. With this ticked, the column mapping needs an Email column instead of an Address column, and rows without an address are kept if one is found for their email.
• Search phone & email for every row - after the import, each imported address is checked against an external data service for a matching email address and phone number, which are added to the recipient's record. 20¢ per lookup; some matches take two lookups for the best accuracy. The Verify your data step states the most this can cost for the rows being imported.

Leave both unticked and no lookup is performed: the email and phone fields stay blank unless you included them in your file.

Blank name fields

If the firstname or lastname columns are blank in your CSV and you do not tick Search phone & email for every row, the recipient's name is left blank. When that recipient receives a mailer, any message variables that reference their name - such as %FIRST_NAME% - will render as empty text.

To avoid blank personalization:

• Fill in name data in your CSV before uploading, or
• Use a fallback phrase directly in your message, such as "Hello neighbor" instead of "Hello %FIRST_NAME%", for sends where names may be missing.

Tips & best practices

• Check the sample rows on Verify your data carefully - a misaligned column (e.g., city and state swapped) will import silently and produce bad mail pieces.
• Map a column to Address before you continue; the mapping step tells you when it is missing.
• After the import, switch on Undeliverable only on the list within a few minutes to check flagged addresses.
• Include email and phone when available - they are used for QR Append on Scan lookups.
• Use custom1-custom4 to carry CRM data (e.g., lead score, agent name) that you can reference in your designs and messages.
• Download a template to start from a correctly formatted file:
  • CSV Template
  • CSV Template (with Absentee)

Limits & gotchas

• Upload .csv, .xlsx, or .xls files. If your file is an Excel workbook, thanks.io will prepare it for import automatically.
• The Verify your data step shows a sample of rows, not the full file.
• Files must be under 20MB.
• Undeliverable addresses don't block the import - they are flagged for review afterward.
• If you start a new list and close the dialog after uploading but before importing, the new list is kept but nothing is imported into it.
• The dob field is required for Birthday campaigns.

Related

• Replacement Variables