Trigger Event - Sequenzy

POST

api

subscribers

events

Trigger Event

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

import requests

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

payload = {
    "email": "<string>",
    "externalId": "<string>",
    "event": "<string>",
    "properties": {},
    "firstName": "<string>",
    "lastName": "<string>",
    "customAttributes": {},
    "occurredAt": "<string>",
    "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({
    email: '<string>',
    externalId: '<string>',
    event: '<string>',
    properties: {},
    firstName: '<string>',
    lastName: '<string>',
    customAttributes: {},
    occurredAt: '<string>',
    eventId: '<string>'
  })
};

fetch('https://api.sequenzy.com/api/v1/subscribers/events', 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",
  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([
    'email' => '<string>',
    'externalId' => '<string>',
    'event' => '<string>',
    'properties' => [
        
    ],
    'firstName' => '<string>',
    'lastName' => '<string>',
    'customAttributes' => [
        
    ],
    'occurredAt' => '<string>',
    '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"

	payload := strings.NewReader("{\n  \"email\": \"<string>\",\n  \"externalId\": \"<string>\",\n  \"event\": \"<string>\",\n  \"properties\": {},\n  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\",\n  \"customAttributes\": {},\n  \"occurredAt\": \"<string>\",\n  \"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")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"email\": \"<string>\",\n  \"externalId\": \"<string>\",\n  \"event\": \"<string>\",\n  \"properties\": {},\n  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\",\n  \"customAttributes\": {},\n  \"occurredAt\": \"<string>\",\n  \"eventId\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"email\": \"<string>\",\n  \"externalId\": \"<string>\",\n  \"event\": \"<string>\",\n  \"properties\": {},\n  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\",\n  \"customAttributes\": {},\n  \"occurredAt\": \"<string>\",\n  \"eventId\": \"<string>\"\n}"

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

{
  "success": true,
  "subscriber": {
    "id": "sub_abc123",
    "email": "user@example.com",
    "externalId": "user_123",
    "created": false
  },
  "event": {
    "id": "evt_xyz789",
    "name": "purchase_completed",
    "definitionCreated": false
  }
}

{
  "success": true,
  "subscriber": {
    "id": "sub_abc123",
    "email": "user@example.com",
    "externalId": null,
    "created": true
  },
  "event": {
    "id": "evt_xyz789",
    "name": "purchase_completed",
    "definitionCreated": false
  },
  "optIn": {
    "required": true,
    "emailQueued": true
  }
}

{
  "success": true,
  "subscriber": {
    "id": "sub_abc123",
    "email": "user@example.com",
    "externalId": "user_123",
    "created": false
  },
  "event": {
    "id": "evt_xyz789",
    "name": "purchase_completed",
    "definitionCreated": false
  },
  "sideEffectFailures": ["apply-sync-rules"]
}

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

{
  "success": false,
  "error": "Subscriber identity conflict: email and externalId point to different subscribers."
}

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

Trigger an event for a subscriber. Creates the subscriber and/or event definition if they don’t exist. Events can trigger automations and apply sync rules.

Request Body

string

Subscriber delivery email address. Required when creating a new subscriber.

string

Your app/customer/user ID for this subscriber. You can trigger events with only externalId when the subscriber already exists.

string

required

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

object

Event properties/metadata. Can contain any key-value data.

string

First name for the subscriber created or updated by this request. Omit to leave an existing value unchanged.

string

Last name for the subscriber created or updated by this request. Omit to leave an existing value unchanged.

object

Custom attributes to set on the subscriber.

string

ISO 8601 timestamp of when the event actually happened. Defaults to now. A timestamp more than an hour in the past records the event as history - see Recording events that already happened.

string

Your own ID for this event, used as an idempotency key on both the live and historical paths. Live retries return duplicate: true; historical retries increment duplicates. See Retrying the same event.

curl -X POST "https://api.sequenzy.com/api/v1/subscribers/events" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "externalId": "user_123",
    "event": "purchase_completed",
    "properties": {
      "orderId": "order_12345",
      "amount": 99.99,
      "product": "Pro Plan",
      "currency": "USD"
    }
  }'

Retrying the Same Event

Producers retry. A queue redelivers, an automation tool re-runs a node, a request times out after it was already handled. Pass your own eventId and Sequenzy treats a repeat as the same occurrence:

curl -X POST "https://api.sequenzy.com/api/v1/subscribers/events" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "event": "saas.purchase",
    "eventId": "order_12345",
    "properties": { "plan": "pro", "amount": 99 }
  }'

For a live event, if this contact already has an event with that ID and that name, nothing is recorded, no sequences enroll, no sync rules apply, no webhooks fire, and the response returns the existing event with duplicate: true:

{
  "success": true,
  "duplicate": true,
  "subscriber": { "id": "sub_123", "email": "user@example.com" },
  "event": { "id": "order_12345", "name": "saas.purchase" }
}

The ID is scoped to the contact and the event name, so keying saas.purchase and saas.refund off the same order ID records both. Without an eventId a repeat is recorded as a second occurrence - we cannot tell a retry from a customer who genuinely bought twice.

This is best-effort, not exactly-once. Events are written to an analytics store that ingests asynchronously, so two calls within about a second of each other can both be recorded. It removes the duplicates that retries and redeliveries actually produce; a producer that needs a strict guarantee should keep its own ledger of what it has sent.

Auto-Creation Behavior

This endpoint automatically creates resources if they don’t exist:

Resource	Behavior
Subscriber	Created if email doesn’t exist - `active` status, or pending confirmation when double opt-in is enabled
Event Definition	Created if event name is new

New subscribers created by this endpoint follow your workspace default lists setting.

What Happens When an Event is Triggered

Event Recorded - Stored in analytics for reporting
Sync Rules Applied - Tags automatically added/removed based on rules
Automations Triggered - Sequences with matching event triggers start

Recording Events That Already Happened

When you migrate from another platform, or backfill history from your own database, you want the events to carry the dates they really happened on. Otherwise every imported purchase looks like it happened today and segments like “purchased in the last 90 days” are wrong. Pass occurredAt to say when the event happened:

curl -X POST "https://api.sequenzy.com/api/v1/subscribers/events" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "event": "saas.purchase",
    "occurredAt": "2024-11-02T10:00:00Z",
    "eventId": "inv_9182",
    "properties": { "plan": "pro", "amount": 99 }
  }'

An occurredAt more than an hour in the past is treated as history, and the behavior changes deliberately:

	Live event	Historical event
Stored with your timestamp	Yes	Yes
Counts for segments and the subscriber timeline	Yes	Yes
Starts or continues sequences	Yes	No
Applies sync rules	Yes	No
Resumes waiting steps, records goal conversions, sends webhooks	Yes	No
Moves the contact’s signup date earlier	No	Yes
Response includes `historical: true`	No	Yes

Historical events never run automations. This is what makes it safe to import years of history in one afternoon: without it, every imported purchase would enroll the contact in your purchase sequence and send a real email. Do not use occurredAt to test a live automation - the side effects you are testing will not run.

Timestamps within the last hour stay on the live path, so queue lag, retries and clock skew behave exactly as before. You can set your flows up first. Importing history is safe whatever order you do it in - build and switch on every sequence you want, then bring your data over. Historical events are also kept out of the calculations that time-based flows use to pick people, so importing a year of purchases will not satisfy a “bought 5 times in the last 30 days” flow, and importing contacts will not make a “joined recently” flow treat them as new arrivals. They still count for the segments and reports themselves - only the enrollment decision ignores them. Signup dates. An event at time T proves the contact existed at T, so a historical event also moves the contact’s signup date back to the earliest event you import - never later. A contact created by the import gets that date instead of today’s, so date-added segments and growth reports do not read a migration as a wave of new signups. Idempotency. Pass eventId and a re-run writes nothing new, exactly as on the live path, but the historical response reports skipped rows through its duplicates count rather than the live path’s duplicate flag and singular event (see Retrying the same event). Imports go further: without an eventId Sequenzy derives a stable ID from the contact, event name, timestamp and properties, so an identical historical event sent twice still produces one row. Live events get no such fallback, because two identical purchases seconds apart are a real thing customers do. Retention. Events are kept for 5 years. A timestamp older than that is rejected with a 400 rather than accepted and silently dropped. To represent a contact who joined longer ago than that, set their signup date with createdAt on Create Subscriber instead - subscriber records have no such limit.

Using `properties` in Sequence Emails

If this event starts a sequence with trigger: "event_received", Sequenzy stores the properties object on that sequence run and makes it available in later emails through event. merge tags. Examples:

{{event.amount}}
{{event.product}}
{{event.order.id}}
{{event.city|your area}}

That means the second or third email in the same sequence can still use the original event payload without copying those values onto the subscriber profile.

Built-in Events

These events have special behavior with default sync rules:

Event	Tags Added	Tags Removed
`saas.purchase`	`customer`	`lead`, `past-due`, `cancelled`, `churned`
`saas.churn`	`churned`	`customer`, `cancelled`, `past-due`
`saas.cancelled`	`cancelled`	`customer`
`saas.payment_failed`	`past-due`	—
`saas.trial_started`	`trial`	`lead`
`saas.trial_cancelled`	`cancelled`	—

Double Opt-In

When the workspace has double opt-in enabled and the event creates a brand-new subscriber, the subscriber is stored pending confirmation, the confirmation email is queued, and sequences triggered by the event wait at their trigger step until the subscriber confirms. The response then includes an optIn object.

Responses

{
  "success": true,
  "subscriber": {
    "id": "sub_abc123",
    "email": "user@example.com",
    "externalId": "user_123",
    "created": false
  },
  "event": {
    "id": "evt_xyz789",
    "name": "purchase_completed",
    "definitionCreated": false
  }
}

{
  "success": true,
  "subscriber": {
    "id": "sub_abc123",
    "email": "user@example.com",
    "externalId": null,
    "created": true
  },
  "event": {
    "id": "evt_xyz789",
    "name": "purchase_completed",
    "definitionCreated": false
  },
  "optIn": {
    "required": true,
    "emailQueued": true
  }
}

{
  "success": true,
  "subscriber": {
    "id": "sub_abc123",
    "email": "user@example.com",
    "externalId": "user_123",
    "created": false
  },
  "event": {
    "id": "evt_xyz789",
    "name": "purchase_completed",
    "definitionCreated": false
  },
  "sideEffectFailures": ["apply-sync-rules"]
}

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

{
  "success": false,
  "error": "Subscriber identity conflict: email and externalId point to different subscribers."
}

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

Response Fields

Field	Description
`subscriber.created`	`true` if subscriber was created by this request
`event.definitionCreated`	`true` if this event type was newly defined
`sideEffectFailures`	Present when the event was recorded but a follow-up stage failed (e.g. `apply-sync-rules`, `trigger-event-automations`). Treat as partial.

Use Cases

E-commerce Purchase

curl -X POST "https://api.sequenzy.com/api/v1/subscribers/events" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "customer@example.com",
    "event": "saas.purchase",
    "properties": {
      "orderId": "ord_abc123",
      "amount": 149.99,
      "plan": "pro-annual",
      "currency": "USD"
    },
    "customAttributes": {
      "lastPurchaseDate": "2024-01-15"
    }
  }'

Feature Activation

curl -X POST "https://api.sequenzy.com/api/v1/subscribers/events" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "event": "feature_activated",
    "properties": {
      "feature": "ai-assistant",
      "firstTime": true
    }
  }'

Subscription Lifecycle

# Trial started
curl -X POST "https://api.sequenzy.com/api/v1/subscribers/events" \
  -d '{ "email": "user@example.com", "event": "saas.trial_started" }'

# Payment failed
curl -X POST "https://api.sequenzy.com/api/v1/subscribers/events" \
  -d '{
    "email": "user@example.com",
    "event": "saas.payment_failed",
    "properties": { "attemptCount": 2 }
  }'

# Customer churned
curl -X POST "https://api.sequenzy.com/api/v1/subscribers/events" \
  -d '{ "email": "user@example.com", "event": "saas.churn" }'

Events can trigger automation sequences. If you have a sequence set to start when this event is received, it will begin automatically for the subscriber.

Trigger Event

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

import requests

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

payload = {
    "email": "<string>",
    "externalId": "<string>",
    "event": "<string>",
    "properties": {},
    "firstName": "<string>",
    "lastName": "<string>",
    "customAttributes": {},
    "occurredAt": "<string>",
    "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({
    email: '<string>',
    externalId: '<string>',
    event: '<string>',
    properties: {},
    firstName: '<string>',
    lastName: '<string>',
    customAttributes: {},
    occurredAt: '<string>',
    eventId: '<string>'
  })
};

fetch('https://api.sequenzy.com/api/v1/subscribers/events', 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",
  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([
    'email' => '<string>',
    'externalId' => '<string>',
    'event' => '<string>',
    'properties' => [
        
    ],
    'firstName' => '<string>',
    'lastName' => '<string>',
    'customAttributes' => [
        
    ],
    'occurredAt' => '<string>',
    '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"

	payload := strings.NewReader("{\n  \"email\": \"<string>\",\n  \"externalId\": \"<string>\",\n  \"event\": \"<string>\",\n  \"properties\": {},\n  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\",\n  \"customAttributes\": {},\n  \"occurredAt\": \"<string>\",\n  \"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")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"email\": \"<string>\",\n  \"externalId\": \"<string>\",\n  \"event\": \"<string>\",\n  \"properties\": {},\n  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\",\n  \"customAttributes\": {},\n  \"occurredAt\": \"<string>\",\n  \"eventId\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"email\": \"<string>\",\n  \"externalId\": \"<string>\",\n  \"event\": \"<string>\",\n  \"properties\": {},\n  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\",\n  \"customAttributes\": {},\n  \"occurredAt\": \"<string>\",\n  \"eventId\": \"<string>\"\n}"

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

{
  "success": true,
  "subscriber": {
    "id": "sub_abc123",
    "email": "user@example.com",
    "externalId": "user_123",
    "created": false
  },
  "event": {
    "id": "evt_xyz789",
    "name": "purchase_completed",
    "definitionCreated": false
  }
}

{
  "success": true,
  "subscriber": {
    "id": "sub_abc123",
    "email": "user@example.com",
    "externalId": null,
    "created": true
  },
  "event": {
    "id": "evt_xyz789",
    "name": "purchase_completed",
    "definitionCreated": false
  },
  "optIn": {
    "required": true,
    "emailQueued": true
  }
}

{
  "success": true,
  "subscriber": {
    "id": "sub_abc123",
    "email": "user@example.com",
    "externalId": "user_123",
    "created": false
  },
  "event": {
    "id": "evt_xyz789",
    "name": "purchase_completed",
    "definitionCreated": false
  },
  "sideEffectFailures": ["apply-sync-rules"]
}

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

{
  "success": false,
  "error": "Subscriber identity conflict: email and externalId point to different subscribers."
}

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

​Request Body

​Retrying the Same Event

​Auto-Creation Behavior

​What Happens When an Event is Triggered

​Recording Events That Already Happened

​Using properties in Sequence Emails

​Built-in Events

​Double Opt-In

​Responses

​Response Fields

​Use Cases

​E-commerce Purchase

​Feature Activation

​Subscription Lifecycle

Request Body

Retrying the Same Event

Auto-Creation Behavior

What Happens When an Event is Triggered

Recording Events That Already Happened

Using `properties` in Sequence Emails

Built-in Events

Double Opt-In

Responses

Response Fields

Use Cases

E-commerce Purchase

Feature Activation

Subscription Lifecycle