`import_subscribers`

Adds a batch of up to 1 000 subscribers to a list in one call and reports record by record.

Call it: to load many addresses at once; for more than 1 000, call it again or use the API (10 000 a request). Each record is email and optional attributes, added as add_subscriber adds one, in order: a new address is created (active, or pending on a list with double opt-in), an address already on the list keeps its status and gets its attributes merged, two records of one address merge into one subscriber. An invalid record (bad email, attributes over their limits) is reported in invalid by its index and fails nothing else.
Needs: an admin key with project_id, or a project key with scope write (its own project; the argument is ignored), and a list that is not deleted; more than 1 000 records is validation_failed and nothing is written.
Returns: created, updated, invalid and pending_confirmation, the same as POST /api/v1/projects/{project_id}/lists/{list_id}/subscribers/import. There is no Idempotency-Key: a repeat adds nothing twice and changes no status (it reports the records as updated).

Arguments

object
list_idstring · uuidrequired

The list to add the subscribers to.
subscribersarray of ImportRecordArgumentrequired

The records, up to 1 000, in order; the result names an invalid one by its index here.

≤ 1000 items
2 fields
- ImportRecordArgument object
- emailstringrequired
  
  The address; any case and surrounding whitespace are normalized.
  
  example ann@example.com
- attributesmap of string → string | number | boolean | null
  
  Attributes to set: a map of string, number or boolean values; null for a key removes it. Up to 64 keys, up to 4 KB of JSON.
  
  default {}
project_idstring · uuid | null

The subscribers’ project. An admin key must pass it; a project key’s own project is used and this is ignored.

No other arguments are accepted.

The result comes back as structuredContent, with the same JSON as a text block.

object · all fields required
createdinteger · uint

Records whose address was not on the list: new subscribers.

≥ 0
invalidarray of InvalidImportRecord

Records not added, by index.
5 fields
- InvalidImportRecord object · all fields required
- codestring
  
  invalid or invalid_type, as in a validation_failed error.
- emailstring
  
  The email as the record had it.
- fieldstring
  
  The record’s field: email, attributes or attributes.<key>.
- indexinteger · uint
  
  The record’s index in subscribers, from 0.
  
  ≥ 0
- messagestring
pending_confirmationinteger · uint

Of the created subscribers, those pending (the list has double opt-in).

≥ 0
updatedinteger · uint

Valid records whose address was already on the list or came earlier in the batch: merged into that subscriber, its status kept.

≥ 0

One record of import_subscribers: the arguments of add_subscriber without the list.

object
emailstringrequired

The address; any case and surrounding whitespace are normalized.

example ann@example.com
attributesmap of string → string | number | boolean | null

Attributes to set: a map of string, number or boolean values; null for a key removes it. Up to 64 keys, up to 4 KB of JSON.

default {}

A record the import did not add, with the first problem of its values.

A failed call answers isError: true with a code from the same table as the HTTP API, and detail. How tools report errors