CSV Upload & Format

What it is

CSV upload lets you populate a mailing list from a spreadsheet file. You map the columns in your file to the fields thanks.io expects, review a preview, and confirm the import.

How to upload a CSV

1. Go to Mailing Lists and open the list you want to populate (or create a new one).
2. Click Upload CSV.
3. Select your .csv file and click Upload.
4. The column mapping screen appears - match each column in your file to the corresponding thanks.io field. If a mapping looks wrong, use the dropdown to select the correct field. If required fields are not mapped, a warning badge appears - fix the mapping before proceeding. Click Save & Preview.
5. Review the preview rows to confirm the data looks correct.
6. Click Confirm.

After import, thanks.io validates addresses. Invalid addresses are flagged in the Invalid Address filter.

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 Message Templates and ~CUSTOM1~–~CUSTOM10~ in Image Templates

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 cannot be combined with Custom 1 or Custom 2.

Reverse-append email and phone (optional)

At the bottom of the upload dialog, you will see a Reverse append email and phone number toggle.

• Yes (on): After the upload, thanks.io checks each imported address against an external data service to find a matching email address and phone number. The results are added to the recipient's record automatically. This costs $0.20 per successful lookup (some records require two lookups at $0.40). You will be prompted to confirm before the charge runs.
• No (off): No lookup is performed. The email and phone fields remain blank unless you included them in your CSV columns.

Blank name fields

If the firstname or lastname columns are blank in your CSV and you do not enable reverse-append, 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 template, such as "Hello neighbor" instead of "Hello %FIRST_NAME%", for sends where names may be missing.

Tips & best practices

• Check sample rows carefully - a misaligned column (e.g., city and state swapped) will import silently and produce bad mail pieces.
• If the Address field is not mapped, the Save & Preview button is blocked. Map a column to Address to proceed.
• After confirming the import, revisit the Invalid Address filter within a few minutes.
• 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 templates.
• Download the CSV template linked in the upload dialog to start from a correctly formatted file.

Limits & gotchas

• Only .csv files are supported. Excel .xlsx must be exported to CSV first.
• The preview shows a sample of rows, not the full file.
• Invalid addresses don't block the import - they are flagged for review in the Invalid Address filter afterward.
• The dob field is required for Birthday campaigns.

Related

• Replacement Variables