Sign in
Subscribers

Import events for many subscribers

Records a bounded batch of up to 25 events for many subscribers. Email is required to create a contact; externalId-only rows must resolve to an existing contact. Events are grouped per contact - a contact whose rows are all more than an hour old is imported silently as history, including no double-opt-in email, while any recent row makes that contact's whole group live. Stable eventIds keep one receipt and let retries re-attempt downstream recovery idempotently.

post/subscribers/events/imports

Request body

Example request

{
  "events": [
    {
      "email": "user@example.com",
      "externalId": "user_123",
      "name": "purchase_completed",
      "eventId": "order_12345"
    }
  ]
}

Response

Import processed. success is false when any event failed - recorded events are kept, so treat errors as partial success.

successboolean
totalinteger

Events submitted in this request.

recordedinteger

Events recorded by this request.

duplicatesinteger

Events skipped because their eventId was already recorded.

failedinteger

Events that failed to record.

sideEffectFailedinteger

Receipt rows whose downstream side effects or historical automation shielding failed. This is orthogonal to receipt accounting and may accompany either recorded or duplicate rows during recovery.

subscribersinteger

Distinct subscriber identities in the request.

errorstring

First failure message when any event failed.

Example response

{
  "success": true
}

Changes