API Reference

Import contacts (CSV)

POST /audiences/:audience_id/contacts/import — bulk-import contacts from a CSV.

POST/audiences/:audience_id/contacts/import

Import up to 10,000 contacts (max 5 MB) from a CSV. The CSV can be sent as a JSON body field or as a raw text/csv / text/plain body. A header row is optional — if present, column names are matched to contact fields (email, first_name, last_name, unsubscribed). By default, any other columns are automatically registered as custom properties (so company, plan, … survive and become {{merge}} tags). Pass create_properties: false for strict mode, where only columns matching an already-registered property are kept and the rest are reported in ignored_columns.

Body

csvstringrequired

CSV text. The email column is always required. Other columns map to contact fields or custom properties. You can also POST a raw text/csv body instead of a JSON wrapper.

on_conflictstringoptional

upsert (default) — update the existing contact when the email already exists. skip — leave it untouched. Can also be passed as a query parameter ?on_conflict=skip when using a raw CSV body.

create_propertiesbooleanoptional

Defaults to true — non-builtin CSV columns are auto-registered as string custom properties (up to 50 new per import) so no data is silently dropped. Set to false (or ?create_properties=false) to keep only already-registered columns.

Request

import { MailBlastr } from 'mailblastr';

const mb = new MailBlastr('mb_xxxxxxxxx');

const { data, error } = await mb.contacts.import({
  audienceId: 'AUDIENCE_ID',
  "csv": "email,first_name,last_name\nsteve@example.com,Steve,Wozniak\nada@example.com,Ada,Lovelace"
});
console.log({ data, error });

Response

{
  "object": "list",
  "imported": 1,
  "updated": 1,
  "skipped": 0,
  "total": 2,
  "ignored_columns": []
}

imported counts net-new contacts; updated counts existing contacts merged by email; skipped counts malformed rows or conflict-skipped rows; total is the sum. ignored_columns lists any CSV header names that did not match a registered property and were therefore not stored.

An empty or invalid CSV returns 422 validation_error. More than 10,000 rows or a body exceeding 5 MB is rejected. An unknown audience returns 404 not_found. See Errors.