Importing your audience

Bringing your existing audience into Letterhead is usually one of the first things you’ll do. 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). To add people one at a time or let them sign up themselves, see Other ways to add contacts.

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). On the company-wide Contacts importer you can also separate them with commas, as other platforms export them (employee, subscriber). 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.

Dates and yes/no values

On the company-wide Contacts importer, date and Yes/No custom fields accept the formats other platforms usually export:

• Dates can be written most common ways, with or without a time: 2019-06-03, 6/3/2019, 6/3/19, June 3, 2019, 3 Jun 2019, or a timestamp such as 2019-06-03T14:30:00Z. Dates with slashes are read month first, so 6/3/2019 is June 3. Dates with dashes or dots and the year last are read day first, so 03-06-2019 is 3 June.
• Yes/No fields take yes/no, y/n, true/false, t/f, on/off, or 1/0, in any letter case.

A value the importer can’t read, like today or maybe, is left blank, and the contact still imports with everything else.

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 Delete many contacts. 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. 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 or subscribed for Subscribed, 2 or not subscribed for Not Subscribed, or 3 or unsubscribed for Unsubscribed. The words work in any letter case, so a status column exported from another platform can be mapped as it is. 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.

A contact who unsubscribed from a newsletter, or was cleaned on it, keeps that status, whatever the cell says: a 1 or subscribed won’t re-subscribe them, and a 2 or not subscribed won’t change them to Not Subscribed. To bring back someone who unsubscribed, they can sign up again, or you can change their status on their contact page.

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.
• A column named after one of Letterhead’s older profile fields (such as Region, Notes, Timezone, Birthday or Latitude) is kept like any other column, and your new field shows under Custom Fields on each contact.
  • The type is fixed. It keeps the older field’s type, so Birthday is a date and Latitude is a number. Letterhead picks that type for you; choosing another stops the import with a note saying which type the column needs.
  • Older values carry over. Contacts who already had a value under that name keep it, now in your field; the import only replaces it for the contacts in your file.
• A few names can’t be kept, because the importer reads them as something else: Email, First Name, Last Name, Tags, Phone, and 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 or yes/no value the importer can’t read (see Dates and yes/no values).
• 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.

Check your import history

On your company-wide Contacts, every import is kept in a history. Open the Imports dropdown on the Audience page and choose Import History. Each import shows:

• File: the file you uploaded.
• Status: In progress, Completed, Failed, Needs field setup (waiting on you to choose which leftover columns to keep), or Cancelled.
• Records: live progress while it runs, then how many contacts were added, updated, and failed.
• Started by and Started: who ran it, and when.

The list refreshes on its own every few seconds while an import is still running.

• See which rows failed. Select the failed-record count to see each address that couldn’t be brought in, and why.
• Retry an import that stopped partway. An import marked Failed offers Retry, which picks up from where it left off rather than starting the file again.

Finish an import that’s waiting on you

An import marked Needs field setup hasn’t imported anything yet. Select Set up fields and continue, choose the columns to keep and their field types, then click Keep N columns and import, or Import without these columns to skip them.

To drop it instead, select Cancel import and confirm. It moves to Cancelled and nothing from the file is imported. If the upload has expired, you’ll need to import the file again, but you can still cancel the waiting import.

Other ways to add contacts

• One at a time: on the Audience page, click Add contact, enter the email address and any other details such as name, status and tags, and submit.
• Signup pages and subscribe forms: readers sign themselves up through your hosted signup pages or a form embedded on your website. See Managing signup pages and subscribe forms.
• Your archive page: when a newsletter’s archive is visible, readers can subscribe at the top of it. See Using your archive and newsletter directory.
• Zapier: add, update and tag contacts from any Zap.
• The Letterhead API: add contacts programmatically.
• Stripe: bring in your Stripe customers as contacts and keep the list current.

With double opt-in on, people who sign up themselves wait in Pending Confirmation until they confirm. If an import or a new contact isn’t behaving the way this page describes, contact support.

Related

• Exporting your audience
• Using profile and custom fields
• Finding your way around Audience