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.

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": "list",
  "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 sum of all 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.