# Import a newsletter list from CSV, safely

> Import email lists safely by running a dry run first, filtering dead domains and syntax errors, and importing only opted-in contacts.

**To import an email list from a CSV safely, run a dry-run validation first to strip out bounces, syntax errors, and previous unsubscribes, and import only with explicit opt-in consent.** Moving a list between systems can damage your sending reputation if the file contains stale addresses, spam traps, or people who opted out. Testing your list before loading it protects your domain so your marketing emails reach the inbox instead of the spam folder.

This guide walks through validating contacts, importing CSV files from popular newsletter platforms, understanding automatic suppression filters, and warming up delivery safely on the [Email](https://thelastapi.dev/docs/email) infrastructure.

## Why newsletter list imports risk your deliverability

When you export an audience from an existing newsletter tool, the file often contains invalid mailboxes, stale domains, and addresses that unsubscribed years ago. If you send an email blast to an unscrubbed list on a fresh sending IP, email providers flag high bounce rates and immediately divert your mail to junk folders.

List hygiene is not just about keeping your records tidy. It directly controls your delivery:

- **Hard bounces.** If more than 2.5% of your recipients bounce on a send, your broadcasts pause automatically to protect your reputation.
- **Spam complaints.** Receiving spam complaints from more than 0.08% of recipients pauses your marketing campaigns. Reaching 0.3% complaints over 30 days blocks marketing sending for the project entirely.
- **Suppression compliance.** Someone who opted out on your old platform must never receive an email from your new platform. Violating unsubscribe requests breaks compliance rules and triggers complaints.

Imports, contact storage, lists, and double opt-in confirmations are completely free. You only pay $0.001 per marketing email sent. Taking the time to filter your file before sending costs nothing and keeps your sending address healthy.

## How the CSV parser handles exports from existing tools

You do not need to rearrange headers or write custom mapping scripts for common platforms. thelastapi automatically parses CSV exports from Mailchimp, Substack, beehiiv, Kit, MailerLite, Buttondown, Ghost, EmailOctopus, and Loops.

The parser scans the header row to detect standard columns:
- **Email:** Matched automatically from common header names.
- **Name:** First and last names are parsed and split appropriately.
- **Status:** Contacts marked as unsubscribed, bounced, or complained in your previous tool retain their status. They will not receive broadcasts.
- **Custom properties:** Any extra columns in the CSV—such as sign-up dates or customer tiers—are stored under the contact's `properties` object.

Files can be up to 15 MB in size or contain up to 100,000 rows per import.

## Previewing data with a dry run

Before committing any records to your database, run an import in dry-run mode. A dry run parses the entire CSV, checks domain records, tests syntax, identifies role addresses, and returns a breakdown of what would be added, updated, or dropped.

With the CLI, use the `--dry-run` flag:

```bash
vibiz email contacts import subscribers.csv --dry-run --list "Newsletter"
```

You can also run a dry run over HTTP:

```bash
curl -X POST https://thelastapi.dev/v1/projects/prj_123/email/contacts/import \
  -H "Authorization: Bearer $VIBIZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "csv": "email,first_name,status\nana@example.com,Ana,subscribed\nbob@gmial.com,Bob,subscribed\ninfo@example.com,Support,subscribed",
    "dry_run": true,
    "lists": ["Newsletter"]
  }'
```

The response returns a report summarizing the valid rows, updated rows, and filtered entries with actionable examples. You can inspect potential issues before any contacts are added to your audience.

## What gets filtered out automatically

When you import a CSV, several classes of problematic addresses are removed automatically. This filtering ensures your list starts clean and stays compliant with [double opt-in and unsubscribe standards](https://thelastapi.dev/blog/double-opt-in-unsubscribe).

| Reason | Example | What happens |
| --- | --- | --- |
| `invalid` | `ann@example`, `not an email` | Dropped. Syntax does not match standard email formats. |
| `typo` | `ann@gmial.com` | Dropped by default. The report suggests `gmail.com`. Add `--fix-typos` or `"fix_typos": true` to fix common domain typos automatically. |
| `role` | `info@`, `sales@`, `no-reply@` | Dropped by default. Add `--include-role` or `"include_role": true` if you deliberately want to send to team mailboxes. |
| `disposable` | Throwaway temporary inboxes | Dropped. These domains expire quickly and cause immediate bounces. |
| `duplicate` | Identical address repeated in file | Dropped. Only one contact record is created or updated. |
| `no_mx` | `user@dead-domain-without-dns.com` | Dropped. The destination domain has no active MX records to receive mail. |
| `unsubscribed` | Marked inactive in prior platform | Retained as `unsubscribed`. They will not receive broadcasts. |
| `bounced` / `complained` | Failed or marked spam previously | Retained with their bad status so they cannot be accidentally contacted. |
| `suppressed` | Listed on the global suppression list | Dropped. These addresses permanently opted out or hard-bounced in past sends. |

If someone previously unsubscribed from your project, importing them again will never quietly resubscribe them. Their record either stays suppressed or enters a `pending` state requiring confirmation if re-added through an app flow.

## Running the live import with consent

To run the import for real, confirm that your subscribers explicitly gave permission to be emailed by your business. Bought, rented, or scraped lists are strictly forbidden. Uploading unverified third-party lists causes spam spikes and leads to account suspension.

When you are ready, run the import with the `--consent` flag:

```bash
vibiz email contacts import subscribers.csv --consent --list "Newsletter" --fix-typos
```

Using the API, pass `"consent": true`:

```bash
curl -X POST https://thelastapi.dev/v1/projects/prj_123/email/contacts/import \
  -H "Authorization: Bearer $VIBIZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "csv": "email,first_name\nana@example.com,Ana\nbill@example.com,Bill",
    "consent": true,
    "fix_typos": true,
    "lists": ["Newsletter"]
  }'
```

If you submit a live import without `"consent": true`, the API rejects the request with a `400 invalid_request` status and error code `consent_required`.

## How email delivery stages new contacts safely

Once your list is imported, sending your first broadcast requires proper configuration and gradual pacing. Marketing email is isolated from transactional mail: newsletters send from `hello@news.<slug>.vibiz.app` (or your own `news.` subdomain) so marketing activity cannot interrupt transactional delivery like password resets or order confirmations. For transactional setup without DNS overhead, review [how to send transactional email from your app without touching DNS](https://thelastapi.dev/blog/send-transactional-email-no-dns).

Before sending marketing mail, configure your sender profile and postal address:

```bash
vibiz email setup
vibiz email settings set \
  --from-name "Acme Updates" \
  --reply-to "hello@acme.com" \
  --postal-address "1 Main St, Springfield, IL 62701, USA"
```

A physical postal address is legally required in all marketing footers under CAN-SPAM regulations. Broadcast reviews will fail with `postal_address_required` if this is omitted.

When you send a broadcast to an imported list, the delivery engine automatically manages risk:

1. **Daily sending limits:** Brand-new marketing sender addresses start with a daily ceiling of 500 emails on day one. This ceiling doubles every clean sending day up to 100,000 emails per day. If your imported list is larger than your daily allowance, the broadcast queues safely across subsequent days.
2. **Stepped rollouts:** For recipients you have never emailed before, sends go out in increments: 2% of the list first, then 5% more, then the remainder in 30-minute intervals while monitoring bounce rates.
3. **Automated pauses:** If hard bounces exceed 2.5% or spam complaints exceed 0.08%, sending halts automatically (`status: paused`) and notifies the project owner by email.

To export your subscribers later, including recorded consent data:

```bash
vibiz email contacts export --status subscribed --out subscribers-clean.csv
```

## Next steps

Start by running `vibiz email contacts import list.csv --dry-run` to see how cleanly your file parses. Once your contacts are imported, set your postal address in settings and create your first campaign draft using `vibiz email broadcast create`.

## Frequently asked questions

### What file formats and size limits apply to CSV imports?

You can upload CSV files up to 15 MB in size or up to 100,000 rows per import request.

### How much does it cost to import a newsletter list?

Importing contacts, storing lists, managing segments, and running dry-run reports are completely free. You only pay $0.001 per marketing email sent from your account balance.

### Can I import role-based addresses like info@ or sales@?

Yes, but they are excluded by default to protect your reputation. You can include them by passing the `--include-role` flag in the CLI or setting `"include_role": true` in the API payload.

### What happens if an imported contact has a misspelled domain?

Common typos like `gmial.com` are caught by the validation parser. Passing `--fix-typos` in the CLI or `"fix_typos": true` in the API payload automatically corrects them to the verified provider.

---

Published 2026-11-15 · https://thelastapi.dev/blog/import-newsletter-list-csv
