Import Events (Many Subscribers)

POST

api

subscribers

events

imports

Import Events (Many Subscribers)

curl --request POST \
  --url https://api.sequenzy.com/api/v1/subscribers/events/imports \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "events": [
    {}
  ],
  "events[].email": "<string>",
  "events[].externalId": "<string>",
  "events[].name": "<string>",
  "events[].properties": {},
  "events[].occurredAt": "<string>",
  "events[].eventId": "<string>"
}
'

import requests

url = "https://api.sequenzy.com/api/v1/subscribers/events/imports"

payload = {
    "events": [{}],
    "events[].email": "<string>",
    "events[].externalId": "<string>",
    "events[].name": "<string>",
    "events[].properties": {},
    "events[].occurredAt": "<string>",
    "events[].eventId": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    events: [{}],
    'events[].email': '<string>',
    'events[].externalId': '<string>',
    'events[].name': '<string>',
    'events[].properties': {},
    'events[].occurredAt': '<string>',
    'events[].eventId': '<string>'
  })
};

fetch('https://api.sequenzy.com/api/v1/subscribers/events/imports', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sequenzy.com/api/v1/subscribers/events/imports",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'events' => [
        [
                
        ]
    ],
    'events[].email' => '<string>',
    'events[].externalId' => '<string>',
    'events[].name' => '<string>',
    'events[].properties' => [
        
    ],
    'events[].occurredAt' => '<string>',
    'events[].eventId' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sequenzy.com/api/v1/subscribers/events/imports"

	payload := strings.NewReader("{\n  \"events\": [\n    {}\n  ],\n  \"events[].email\": \"<string>\",\n  \"events[].externalId\": \"<string>\",\n  \"events[].name\": \"<string>\",\n  \"events[].properties\": {},\n  \"events[].occurredAt\": \"<string>\",\n  \"events[].eventId\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.sequenzy.com/api/v1/subscribers/events/imports")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"events\": [\n    {}\n  ],\n  \"events[].email\": \"<string>\",\n  \"events[].externalId\": \"<string>\",\n  \"events[].name\": \"<string>\",\n  \"events[].properties\": {},\n  \"events[].occurredAt\": \"<string>\",\n  \"events[].eventId\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.sequenzy.com/api/v1/subscribers/events/imports")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"events\": [\n    {}\n  ],\n  \"events[].email\": \"<string>\",\n  \"events[].externalId\": \"<string>\",\n  \"events[].name\": \"<string>\",\n  \"events[].properties\": {},\n  \"events[].occurredAt\": \"<string>\",\n  \"events[].eventId\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "total": 2,
  "recorded": 2,
  "duplicates": 0,
  "failed": 0,
  "sideEffectFailed": 0,
  "subscribers": 2
}

{
  "success": false,
  "total": 2,
  "recorded": 1,
  "duplicates": 0,
  "failed": 1,
  "sideEffectFailed": 0,
  "subscribers": 2,
  "failures": [{ "index": 1, "error": "Subscriber identity conflict" }],
  "error": "Subscriber identity conflict"
}

{
  "success": false,
  "total": 1,
  "recorded": 1,
  "duplicates": 0,
  "failed": 0,
  "sideEffectFailed": 1,
  "subscribers": 1,
  "sideEffectFailures": [{ "index": 0, "stages": ["automation-triggering"] }],
  "error": "One or more events were recorded, but downstream side effects failed."
}

{
  "success": false,
  "error": "events[3] needs an email or an externalId."
}

{ "success": false, "error": "Unauthorized" }

{
  "success": false,
  "error": "API key is missing required scope: automations:trigger"
}

{ "success": false, "error": "Internal server error" }

Record a bounded batch of up to 25 events for many subscribers in one request - the pipeline companion to Trigger Event and Trigger Events (Bulk), built for data pipelines and warehouse syncs. Each event carries its own subscriber identity. Events are grouped per contact:

A contact whose events are all more than an hour old is imported as history in one idempotent write: stored with real timestamps, visible to segments and the timeline, but no sequences, sync rules, waiting steps, goals, webhooks, or double-opt-in confirmation emails run.
A contact with any recent event takes the live path with normal side effects, processed in order.

Contacts process independently, so an error response may still include recorded events. Treat errors as partial success and retry the same request - with an eventId on every event, a retry records nothing twice.

Request Body

object[]

required

One to 25 events. Every event requires a name, a source-owned eventId, and an email or an externalId. Email is required when creating a contact; an external-ID-only row must resolve to an existing contact. null identifier and timestamp values are treated as absent, so warehouse exports with null columns import cleanly. Keys outside the documented fields are ignored - keep row data inside properties, or it is silently discarded.

string

Subscriber delivery email address. Required when the event may create a new contact.

string

Your app/customer/user ID for this subscriber. It can be used without email only when it resolves to an existing contact.

string

required

Event name (e.g., purchase_completed, saas.purchase)

object

Event properties/metadata.

string

ISO 8601 timestamp of when the event actually happened. Defaults to now. Classification is per contact: only when all rows for that contact are more than an hour old is the group historical. Any recent row makes every event for that contact live while preserving each supplied timestamp.

string

required

Your source-owned ID for this event, used as an idempotency key on both the live and historical paths. Derive it from your source data (an order ID, a warehouse row key) so re-running the import is safe.

curl -X POST "https://api.sequenzy.com/api/v1/subscribers/events/imports" \
  -H "Authorization: Bearer API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "email": "one@example.com",
        "name": "purchase_completed",
        "eventId": "order_1001",
        "occurredAt": "2026-08-01T12:00:00Z",
        "properties": { "amount": 99.99 }
      },
      {
        "email": "two@example.com",
        "externalId": "user_42",
        "name": "purchase_completed",
        "eventId": "order_1002",
        "occurredAt": "2026-08-02T09:30:00Z",
        "properties": { "amount": 49.99 }
      }
    ]
  }'

Responses

{
  "success": true,
  "total": 2,
  "recorded": 2,
  "duplicates": 0,
  "failed": 0,
  "sideEffectFailed": 0,
  "subscribers": 2
}

{
  "success": false,
  "total": 2,
  "recorded": 1,
  "duplicates": 0,
  "failed": 1,
  "sideEffectFailed": 0,
  "subscribers": 2,
  "failures": [{ "index": 1, "error": "Subscriber identity conflict" }],
  "error": "Subscriber identity conflict"
}

{
  "success": false,
  "total": 1,
  "recorded": 1,
  "duplicates": 0,
  "failed": 0,
  "sideEffectFailed": 1,
  "subscribers": 1,
  "sideEffectFailures": [{ "index": 0, "stages": ["automation-triggering"] }],
  "error": "One or more events were recorded, but downstream side effects failed."
}

{
  "success": false,
  "error": "events[3] needs an email or an externalId."
}

{ "success": false, "error": "Unauthorized" }

{
  "success": false,
  "error": "API key is missing required scope: automations:trigger"
}

{ "success": false, "error": "Internal server error" }

Counts

total = recorded + duplicates + failed. duplicates counts events whose eventId was already recorded for that contact and event name, so no second receipt was written. Live duplicate retries may idempotently re-attempt downstream recovery. sideEffectFailed is orthogonal to receipt accounting: it can accompany either a newly recorded row or a duplicate row whose downstream work (or historical automation shielding) still failed. subscribers is the number of distinct identities in the request.

Throughput

At 25 events per request within the standard rate limits, this endpoint sustains up to 2,500 events per minute while keeping each synchronous request bounded - use it instead of looping over the single-subscriber endpoints when syncing events from a pipeline or warehouse. See the data pipeline ingestion guide for the full recipe.

Import Events (Many Subscribers)

curl --request POST \
  --url https://api.sequenzy.com/api/v1/subscribers/events/imports \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "events": [
    {}
  ],
  "events[].email": "<string>",
  "events[].externalId": "<string>",
  "events[].name": "<string>",
  "events[].properties": {},
  "events[].occurredAt": "<string>",
  "events[].eventId": "<string>"
}
'

import requests

url = "https://api.sequenzy.com/api/v1/subscribers/events/imports"

payload = {
    "events": [{}],
    "events[].email": "<string>",
    "events[].externalId": "<string>",
    "events[].name": "<string>",
    "events[].properties": {},
    "events[].occurredAt": "<string>",
    "events[].eventId": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    events: [{}],
    'events[].email': '<string>',
    'events[].externalId': '<string>',
    'events[].name': '<string>',
    'events[].properties': {},
    'events[].occurredAt': '<string>',
    'events[].eventId': '<string>'
  })
};

fetch('https://api.sequenzy.com/api/v1/subscribers/events/imports', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sequenzy.com/api/v1/subscribers/events/imports",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'events' => [
        [
                
        ]
    ],
    'events[].email' => '<string>',
    'events[].externalId' => '<string>',
    'events[].name' => '<string>',
    'events[].properties' => [
        
    ],
    'events[].occurredAt' => '<string>',
    'events[].eventId' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sequenzy.com/api/v1/subscribers/events/imports"

	payload := strings.NewReader("{\n  \"events\": [\n    {}\n  ],\n  \"events[].email\": \"<string>\",\n  \"events[].externalId\": \"<string>\",\n  \"events[].name\": \"<string>\",\n  \"events[].properties\": {},\n  \"events[].occurredAt\": \"<string>\",\n  \"events[].eventId\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.sequenzy.com/api/v1/subscribers/events/imports")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"events\": [\n    {}\n  ],\n  \"events[].email\": \"<string>\",\n  \"events[].externalId\": \"<string>\",\n  \"events[].name\": \"<string>\",\n  \"events[].properties\": {},\n  \"events[].occurredAt\": \"<string>\",\n  \"events[].eventId\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.sequenzy.com/api/v1/subscribers/events/imports")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"events\": [\n    {}\n  ],\n  \"events[].email\": \"<string>\",\n  \"events[].externalId\": \"<string>\",\n  \"events[].name\": \"<string>\",\n  \"events[].properties\": {},\n  \"events[].occurredAt\": \"<string>\",\n  \"events[].eventId\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "total": 2,
  "recorded": 2,
  "duplicates": 0,
  "failed": 0,
  "sideEffectFailed": 0,
  "subscribers": 2
}

{
  "success": false,
  "total": 2,
  "recorded": 1,
  "duplicates": 0,
  "failed": 1,
  "sideEffectFailed": 0,
  "subscribers": 2,
  "failures": [{ "index": 1, "error": "Subscriber identity conflict" }],
  "error": "Subscriber identity conflict"
}

{
  "success": false,
  "total": 1,
  "recorded": 1,
  "duplicates": 0,
  "failed": 0,
  "sideEffectFailed": 1,
  "subscribers": 1,
  "sideEffectFailures": [{ "index": 0, "stages": ["automation-triggering"] }],
  "error": "One or more events were recorded, but downstream side effects failed."
}

{
  "success": false,
  "error": "events[3] needs an email or an externalId."
}

{ "success": false, "error": "Unauthorized" }

{
  "success": false,
  "error": "API key is missing required scope: automations:trigger"
}

{ "success": false, "error": "Internal server error" }

​Request Body

​Responses

​Counts

​Throughput

Request Body

Responses

Counts

Throughput