How Do I Import Subscribers?

Letterhead’s guided CSV importer maps your file’s columns to Letterhead fields, validates rows before anything is saved, and updates existing contacts automatically. You can import .csv files as well as Excel files (.xls/.xlsx).

Prefer to have it done for you?

Penpal can help prepare or troubleshoot an import for you in conversation — for example, “why did my CSV import fail?” See how Penpal works.

Prepare your file

Include these columns:

• Email Address — required.
• Subscription Status — optional. Enter one of these words (not case-sensitive): Subscribed, Not Subscribed, Unsubscribed, Cleaned, Disengaged, or Pending Reengagement. Leave it blank, or enter anything else — including a number — and the row is imported as Unsubscribed, not left untouched, so don’t guess if you’re not sure of the exact word.
• Tags — optional. Separate multiple tags with a | symbol (for example employee|subscriber|IT-Department). Tags can’t contain spaces — use dashes instead, e.g. VIP-Guest-List.
• Any custom fields you want to fill, and — if you’re on the classic per-channel audience — any profile fields too. Columns matching existing field names are populated automatically. On the classic per-channel importer you can’t create new fields during an import; on the company-wide Contacts importer you can keep a column that matches no field as a new custom field. On the newer company-wide Contacts experience, column mapping only offers Email, First Name, Last Name, Tags, a status column per channel, and your own custom fields — the built-in profile fields aren’t mapping options there.

Run the import

1. Go to Audience, open the dropdown on Add contact, and select Import CSV.
2. Choose an import type — Add & Update (new contacts are added; contacts whose email already exists have their status and tags updated from the CSV) is always offered. If you’re on the classic per-channel audience, you’ll also see Delete & Overwrite, which deletes all current contacts and replaces them with the imported list — use with care; see Mass Deletion of Subscriber Contact Details. On the newer company-wide Contacts experience, only Add & Update is available.
3. Upload your file (or drag and drop it).
4. Map columns — match each column in your file to a Letterhead field. On the classic per-channel importer, unmapped columns are skipped. On the company-wide Contacts importer, you’ll get a chance to keep them after you click Import.
5. Review & finalize — the importer highlights any validation errors and lets you edit values in place. If your Subscription Status column has numbers, blanks, or any spelling other than the words listed above, use Find and replace to convert them before finishing — otherwise those rows will import as Unsubscribed.
6. Click Import.

The import runs in the background. Organization/brand administrators receive a confirmation email when it completes, and the new subscribers appear on the Audience page.

Import at the workspace level

The steps above import into a single channel. To seed subscribers across all of your newsletters from one file, run the import from the workspace level instead: go to Audience → Contacts → Imports.

For a workspace import, your CSV needs one column for every newsletter, identified by the channel’s slug. Each of those columns holds that contact’s subscription status for that channel — enter 1 for Subscribed, 2 for Not Subscribed, or 3 for Unsubscribed. Leave a cell blank, or enter any other value, and that channel’s existing status for the contact is left unchanged — it’s not treated as a request to exclude them.

So alongside Email Address, add one column per channel slug and fill in the per-channel status on each row, then map each channel column during the import. The rest of the flow — import type, mapping, and validation — works the same as a single-channel import.

Keep columns that don’t match a field

On the company-wide Contacts importer, a column you didn’t match to a contact field isn’t silently dropped. After you click Import, Letterhead lists every such column with a few example values from your file, and you choose what to keep. A file where every column matched goes straight through, with no extra step.

1. Tick Keep next to each column you want. Anything you leave unticked is skipped.
2. Check the Field type for each one. Letterhead suggests a type from your values; ZIP codes and phone numbers are suggested as text so their leading zeros survive.
3. Click Keep N columns and import. Letterhead creates a custom field for each kept column, named after its header, and the same import fills it in — you don’t upload the file again. To skip them all, click Import without these columns.

A few things worth knowing:

• If you already have a custom field with that name, the column goes into it — the list says Goes into your existing field and the type is the field’s own.
• Some names can’t be kept, because Letterhead already uses them (for example Source, Tags, Phone, or one of your channel slugs). Rename the column in your file and import again to keep it.
• A cell that doesn’t fit its field’s type is left out, and that contact still imports with everything else. That includes empty cells, a number with a leading zero or a +, and a date that isn’t one complete calendar day.
• If another column you mapped already feeds that field, its value wins on each row; the kept column only fills the rows where it’s empty.
• You can keep up to 50 columns per import.

Closing the window doesn’t decide anything. The import waits in Import History as Needs field setup, with nothing imported yet, until you choose its columns or cancel it. When you next open the importer, Letterhead offers to continue it. See Finish an import that’s waiting on you.

Related

• How can I add a subscriber to my account? — all the ways to add contacts, one at a time or in bulk.
• Export your audience
• Working in Audience
• See your audience import history and retry a failed import — for imports run from your company’s Contacts page.