Postwind Pre-release Download
Docs menu Import subscribers

Generated from Postwind commit a19b2e4 OpenAPI 0.1.0 synced

POST/api/v1/projects/{project_id}/lists/{list_id}/subscribers/import

Needs scope: writeIdempotency-KeyMCP tool: import_subscribers operationId import_subscribers

Import subscribers

Adds up to 10 000 records to the list in one request, each by the rule of add_subscriber (normalized email, attributes merged, status by the list), as if added one by one in order, and answers record by record. An invalid record is reported by its index and fails nothing else; two records of one address are merged into one subscriber in order. Needs scope write. A repeat adds nothing twice and changes no status.

Parameters

NameInTypeDescription
project_idrequired path string · uuid The project’s id
list_idrequired path string · uuid The list’s id
Idempotency-Key header string

1–128 characters · pattern ^[!-~]{1,128}$

 A key of the client’s choosing, one per request it means to send once (a UUID will do). A repeat with the same key and the same body within 24 h creates nothing again and gets the first answer, marked Idempotent-Replayed: true. The key belongs to the API key that sent it. Only a 2xx answer is kept: after any other answer the key is free again.

Request body

application/json · required

  • ImportSubscribersRequest object · all fields required
  • subscribersarray of CreateSubscriberRequest

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

    ≤ 10000 items

    2 fields
    • CreateSubscriberRequest object · all fields required
    • attributesobject

      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.

    • emailstring · email

      The address; any case and surrounding whitespace are normalized.

      example ann@example.com

Responses

200

The import’s report

HeaderTypeDescription
Idempotent-Replayedstring · enumtrue when the answer is a replay of an earlier request with the same Idempotency-Key; absent otherwise.
  • SubscriberImportReport object · all fields required
  • createdinteger

    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 errors of a 422.

      example invalid

    • emailstring

      The email as the record had it.

    • fieldstring

      The record’s field: email, attributes or attributes.<key>.

      example email

    • indexinteger

      The record’s index in subscribers, from 0.

      ≥ 0

    • messagestring
  • pending_confirmationinteger

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

    ≥ 0

  • updatedinteger

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

    ≥ 0

400

Not JSON (invalid_json)

Problem (application/problem+json)

401

No valid key

Problem (application/problem+json)

403

A project key without scope write (forbidden)

Problem (application/problem+json)

404

No such project or list, or another project’s (not_found)

Problem (application/problem+json)

409

The project or list is deleted (conflict); or a request with the same Idempotency-Key has not answered yet (idempotency_key_in_progress)

Problem (application/problem+json)

413

Over 10 MB (body_too_large)

Problem (application/problem+json)

415

Not application/json (unsupported_media_type)

Problem (application/problem+json)

422

The body’s shape, every problem in errors (validation_failed; a record’s field is named subscribers.<index>.<field>), or more than 10 000 records (subscribers / invalid); nothing is written; or the Idempotency-Key was used in the last 24 h for another request (idempotency_key_reused), or is not 1 to 128 visible ASCII characters (validation_failed, field Idempotency-Key)

Problem (application/problem+json)

429

The key is over its rate limit, api.rate_limit_per_minute requests a minute on this node (rate_limited)

HeaderTypeDescription
Retry-AfterintegerSeconds until the key’s next request passes; rounded up.

Problem (application/problem+json)

504

Postwind’s storage did not answer within its time limit (storage_timeout). A change the request makes may still take effect: check before repeating it. A repeat with the same Idempotency-Key never runs it twice: it is 409 idempotency_key_in_progress until the key’s 24 h end

Problem (application/problem+json)