CSV Import With Field Mapping Without Wrecking Your List

A CSV import with field mapping looks like a technical, boring chore. Right up to the moment it breaks the list the whole company’s communication rests on. A few minutes of inattention while uploading a file can cost weeks of rebuilding sender reputation. We write about this from the perspective of a team that runs its own fleet of sending servers and watches the results of other people’s imports in delivery logs. Below is the procedure we use ourselves when migrating databases into MailCraft.

What breaks during a CSV import and why

The consequences of a bad import are always the same. Duplicated records, because the matching key landed on the first name column instead of the address. First names in the surname field, because the columns in the file were in a different order than in the database. And personalisation that substitutes nothing and sends a greeting without a name to half the list.

A contact database is not a spreadsheet. A wrong row in a spreadsheet is simply ugly. A wrong row in a sending database is a potential bounce. Hard bounces after uploading an old, uncleaned list can trigger throttling at the large filters – first they slow down accepting mail, then they refuse connections. Getting out of that is measured in weeks of careful sending, not in one phone call to support.

Consent is a separate layer of the problem. A file with no column for the source and date of consent breaks not only the data, but the legal compliance of every campaign that follows. After the import you will no longer reconstruct where a given address came from. Ever.

A rule from our practice: an import is an operation on production. Not a rough draft, not a test, not “let’s see what comes out”. Treat it like deploying a change to a live system.

Preparing the file before the import

Start with the encoding. The file has to be UTF-8 without BOM. Otherwise accented characters fall apart at the preview stage, and the BOM marker sticks to the name of the first column and breaks its mapping. Second point: the separator. The CSV standard says comma, but the Polish version of Excel writes a semicolon, because in Poland the comma is the decimal separator. Check what you actually have instead of assuming.

Fields with a comma inside, a postal address for example, have to be wrapped in quotation marks. The same goes for multi-line values. There has to be one header row, in the first line, with no empty columns and no merged cells. A merged cell turns into a shifted row after export.

• Encoding: UTF-8 without BOM, accented characters readable in the raw file
• Separator: one, consistent across the whole file
• Headers: unique, no trailing spaces, no duplicated names
• Dates: ISO format, so YYYY-MM-DD
• Phone numbers: one uniform notation, ideally with the country prefix, no spaces and no hyphens
• End of file: zero empty rows under the last record

Tip: open the file in a text editor, not in a spreadsheet. You will see the raw structure instead of Excel’s interpretation, which quietly strips leading zeros and converts dates into its own format.

Field mapping: the key, data types, default values

The primary key is the email address and only the address. Before matching, it has to be normalised: trim whitespace on both sides, lowercase it, strip the invisible characters that like to ride along when you copy from a spreadsheet. Without that, “Jan@Firma.pl ” and “jan@firma.pl” are two different contacts as far as the system is concerned.

Map column by column, by hand. Automatic matching on header names looks convenient, but the header “name” is sometimes a first name, sometimes a company name, and sometimes it holds the full first and last name in one field. Guessing costs more here than a minute of clicking.

Watch the data types. Text, number, date, the boolean consent value – each of these fields behaves differently in filtering and segmentation. Dates in a regional format are a source of silent errors, because 03.04 means something different on each side of the Atlantic. And the columns you cannot assign? Leave them unmapped. Forcing them into an existing field turns a decent database into a dumping ground. The range of custom fields, filters and segmentation rules is described in the platform feature overview.

Personalisation and empty cells – how to test substitutions before sending

Set a default value for every variable used in the content. Without a fallback, instead of “Hi Anna” you send “Hi ,”. After mapping, filter the list by the empty first name field and send the test to exactly those records. Checking substitutions on a complete contact proves nothing.

Deduplication and updating existing records

For a contact already sitting in the database you have three strategies: skip existing, overwrite all fields, fill only the empty ones. By default, choose filling the empty ones. A bulk overwrite wipes data collected earlier from forms, where people typed their own name in themselves – and an external file often has that same field empty or in worse quality.

Duplicates also sit inside the file itself, not only in relation to the database. The same address in two rows, a different first name and a different company in each. The system has to know which row wins before it starts writing. Aliases and plus addresses in the style of jan+newsletter@firma.pl are a separate topic. Technically they land in the same mailbox, formally they are a different address and they behave differently under filtering on the recipient’s side. We treat them as separate contacts unless the client deliberately decides otherwise.

Never delete unsubscribed records. An address on the opt-out list has to stay there after a re-import as well, because otherwise it comes back into sending as a “new” contact. The simplest way to earn a complaint and the most common mistake when migrating between systems.

What to do with a data conflict – the “newer wins” rule

It sounds sensible, but it works only when the file has a column with the record’s update date. Without it, “newer” only means “uploaded later”, which is sometimes exactly the opposite of the truth.

Validation and consent: GDPR and PKE article 398

Syntax validation is the first step, not the last. A correctly built address can point at a domain that does not exist or has no MX record. Check in order: syntax, existence of the domain, presence of MX. This whole chain can be run without sending a single message to the address. Let role addresses of the info@, office@, contact@ type through only deliberately – they reach several people, they generate complaints and they have weak engagement, so they drag the list statistics down.

The law makes no exception here for B2B. Marketing consent is required for sending to company addresses too, and a tax number in the database legalises nothing. Poland’s electronic communications law, PKE, and article 398 in particular, requires the recipient’s prior consent to receive commercial information, and GDPR requires you to be able to demonstrate that consent.

That is why you add evidence columns to the import:

• the source of consent, meaning the specific form, campaign or touchpoint
• the date and time it was given
• the wording of the clause as it stood at the moment of sign-up
• the IP address, if the consent came from an online form

We do not let purchased databases onto our fleet. This is not a matter of marketing principles, but of legal compliance and of protecting the reputation of the IP addresses all our clients send from. If you want to see what legally compliant list handling looks like in practice, take a look at the MailCraft email marketing platform and the way we keep the consent records there.

The trial import, or how not to flatten your database with one click

The backup of the list is made before the import, not after. The reverse order costs a lot of nerves and usually ends with manually stitching data back together from exports. Then upload a sample: twenty to fifty rows onto a separate test list. Look at the finished records in the database, not at the mapping preview screen – the preview shows intent, the record shows the result.

1. Back up the target list.
2. Import a sample onto a separate test list.
3. Inspect a few finished records field by field.
4. Send a personalisation test, including to contacts with empty fields.
5. Run the full import.
6. Check the record count, duplicates and rejects after the import.

Tip: import into a new segment, not into the main list. Keep it separate until you see the first delivery statistics. A segment is easy to switch off, a mixed list has to be untangled afterwards.

We admit a limitation: undoing an import with one button is a feature we have on the roadmap, not in the panel. Today the rescue is a backup and a separate list. We would rather say that outright than let you import without a safety net.

After the import: sending, warmup and observation

A large batch of new addresses changes the profile of outgoing traffic. Filters on the recipients’ side see that and react, even if the content is identical to previous campaigns. Split the first send to a fresh segment into smaller batches instead of firing the whole list at once. Watch the reaction after each batch and only then increase the volume.

The technical layer has to be in place before the import, not after it. SPF, DKIM, DMARC, a consistent Return-Path matching the signing domain, a correct PTR record for the sending address. Fixing that mid-campaign means part of the send has already gone out with a worse result.

In the first sends, look at four things: hard bounces, soft bounces, complaints and the open rate broken down by import source. That breakdown tells you which batch of data was weak. Switch off records generating a hard bounce right away, not at the next campaign – a repeated send to a non-existent mailbox is a clear signal to the filter.

From the experience of running our own fleet of sending servers: we run a freshly imported segment separately, like new traffic. Only after a few clean campaigns do we merge it with the rest of the database.

Summary

A CSV import with field mapping is safe when it is boring and repeatable. The whole trick is doing the same thing every time, in the same order, with no shortcuts under time pressure.

Three pillars stay unchanged. A clean file, prepared and checked in its raw form. Deliberate mapping with the key set on the normalised address. A trial import before the full one, on a separate list, with a personalisation test.

Consent and the proof of it are not an add-on to a contact, they are part of it – as important as the address. A database without that information is incomplete, no matter how many records it holds. Sender reputation depends on list quality more than on campaign content, because the best copy will not save a send to addresses that do not exist or that nobody asked for.

If you are planning a migration of a larger database, write to our team. We will go through the file and the mapping together, before anything reaches production. When the data is meant to flow automatically from a CRM or a shop instead of from a file, it is worth considering connecting your database through an integration instead.