API Reference

Import contacts (array)

POST /audiences/:audience_id/contacts/batch — bulk-import contacts from a JSON array.

POST/audiences/:audience_id/contacts/batch

Import up to 10,000 contacts in a single request by sending a JSON array. Invalid rows (missing or malformed email) are counted as skipped and never cause the whole request to fail.

Body

contactsarrayrequired

Array of contact objects to import. You can also send a bare JSON array as the body instead of wrapping it in { contacts: [...] }.

contacts[].emailstringrequired

Email address. Rows with a missing or invalid email are skipped.

contacts[].first_namestringoptional

Optional first name.

contacts[].last_namestringoptional

Optional last name.

contacts[].unsubscribedbooleanoptional

Optional opt-out flag. Defaults to false.

contacts[].propertiesobjectoptional

Optional map of custom property key/value pairs. Unlike POST /contacts, this endpoint does not check keys against your contact-property registry — any key matching \w{1,64} is accepted and stored (up to 50 keys per contact, values truncated at 1000 characters). Unregistered keys are written to the contact but have no declared type or fallback, so register them with POST /contact-properties if you want them usable as merge tags.

on_conflictstringoptional

upsert (default) — update the existing contact when the email already exists. skip — leave the existing contact untouched.

Request

import { Mailblastr } from 'mailblastr';

const mb = new Mailblastr('mb_xxxxxxxxx');

const { data, error } = await mb.contacts.batch({
  audienceId: 'AUDIENCE_ID',
  "contacts": [
    { "email": "steve@example.com", "first_name": "Steve", "last_name": "Wozniak" },
    { "email": "ada@example.com", "first_name": "Ada", "last_name": "Lovelace" }
  ]
});
console.log({ data, error });

Response

{
  "object": "contact_import",
  "imported": 1,
  "updated": 1,
  "skipped": 0,
  "total": 2
}

imported counts net-new contacts; updated counts existing contacts that were merged; skipped counts rows that were invalid or left untouched due to on_conflict: skip; total is the number of valid, email-deduplicated rows that were processed — rows rejected for a missing or invalid email are counted in skipped only, and duplicate emails inside one payload collapse into a single row, so total is not the sum of the other three.

An empty or entirely-invalid contacts array returns 422 validation_error. More than 10,000 rows per request is rejected with 422 validation_error. An unknown audience returns 404 not_found. See Errors.