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 profile fields or custom fields you want to fill. Columns matching existing field names are populated automatically; you can’t create new fields during an import.

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.
   • Delete & Overwrite — all current contacts are deleted and replaced with the imported list. Use with care; see Mass Deletion of Subscriber Contact Details.
3. Upload your file (or drag and drop it).
4. Map columns — match each column in your file to a Letterhead field. Unmapped columns are skipped, and you can’t add new fields here.
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.

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.