> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sequenzy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Trigger Events (Bulk)

> Trigger multiple events for a subscriber in one request

Trigger multiple events for a subscriber in one request. Creates the subscriber and/or event definitions if they don't exist.

<Note>
  Events are processed independently. If one event fails, previously triggered
  events are not rolled back, so retry an error response as a partial success.
</Note>

## Request Body

<ParamField body="email" type="string">
  Subscriber delivery email address. Required when creating a new subscriber.
</ParamField>

<ParamField body="externalId" type="string">
  Your app/customer/user ID for this subscriber. You can trigger events with
  only `externalId` when the subscriber already exists.
</ParamField>

<ParamField body="events" type="array" required>
  Array of events to trigger
</ParamField>

<ParamField body="events[].name" type="string" required>
  Event name
</ParamField>

<ParamField body="events[].properties" type="object">
  Event properties/metadata
</ParamField>

<ParamField body="customAttributes" type="object">
  Custom attributes to set on the subscriber.
</ParamField>

```bash theme={null}
curl -X POST "https://api.sequenzy.com/api/v1/subscribers/events/bulk" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "externalId": "user_123",
    "events": [
      {
        "name": "page_viewed",
        "properties": { "page": "/pricing", "duration": 45 }
      },
      {
        "name": "feature_used",
        "properties": { "feature": "export", "format": "csv" }
      }
    ]
  }'
```

## 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 Definitions** | Each event type created if new                                                                          |

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

## Double Opt-In

When the workspace has double opt-in enabled and this request creates a brand-new subscriber, the subscriber is stored pending confirmation and a single confirmation email is queued for the whole request. All events are still recorded, and sequences triggered by them wait at their trigger step until the subscriber confirms. The response then includes an `optIn` object.

## Responses

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "subscriber": {
      "id": "sub_abc123",
      "email": "user@example.com",
      "externalId": "user_123",
      "created": false
    },
    "events": [
      {
        "id": "evt_1",
        "name": "page_viewed",
        "definitionCreated": false
      },
      {
        "id": "evt_2",
        "name": "feature_used",
        "definitionCreated": true
      }
    ]
  }
  ```

  ```json 200 (new subscriber, double opt-in enabled) theme={null}
  {
    "success": true,
    "subscriber": {
      "id": "sub_abc123",
      "email": "user@example.com",
      "externalId": null,
      "created": true
    },
    "events": [
      {
        "id": "evt_1",
        "name": "page_viewed",
        "definitionCreated": false
      },
      {
        "id": "evt_2",
        "name": "feature_used",
        "definitionCreated": true
      }
    ],
    "optIn": {
      "required": true,
      "emailQueued": true
    }
  }
  ```

  ```json 401 theme={null}
  {
    "success": false,
    "error": "Unauthorized"
  }
  ```

  ```json 500 theme={null}
  {
    "success": false,
    "error": "Internal server error"
  }
  ```
</ResponseExample>

## Response Fields

| Field                         | Description                                                                                 |
| ----------------------------- | ------------------------------------------------------------------------------------------- |
| `subscriber.created`          | `true` if subscriber was created by this request                                            |
| `events[].definitionCreated`  | `true` if this event type was newly defined                                                 |
| `events[].sideEffectFailures` | Present when that event was recorded but a follow-up stage failed (e.g. `apply-sync-rules`) |
| `optIn`                       | Present when the new subscriber requires double opt-in confirmation before becoming active  |

## Use Cases

### Track User Session

```bash theme={null}
curl -X POST "https://api.sequenzy.com/api/v1/subscribers/events/bulk" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "events": [
      { "name": "session_started" },
      { "name": "page_viewed", "properties": { "page": "/dashboard" } },
      { "name": "feature_used", "properties": { "feature": "reports" } },
      { "name": "page_viewed", "properties": { "page": "/settings" } }
    ]
  }'
```

### Record Funnel Progress

```bash theme={null}
curl -X POST "https://api.sequenzy.com/api/v1/subscribers/events/bulk" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "events": [
      { "name": "checkout_started", "properties": { "cartValue": 149.99 } },
      { "name": "payment_method_added", "properties": { "type": "card" } },
      { "name": "checkout_completed", "properties": { "orderId": "ord_123" } }
    ]
  }'
```

### Batch Import Historical Events

```bash theme={null}
curl -X POST "https://api.sequenzy.com/api/v1/subscribers/events/bulk" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "events": [
      { "name": "saas.purchase", "properties": { "plan": "starter" } },
      { "name": "saas.upgrade", "properties": { "from": "starter", "to": "pro" } }
    ],
    "customAttributes": {
      "currentPlan": "pro",
      "lifetimeValue": 599.00
    }
  }'
```

<Note>
  Each event in the bulk request is processed independently. Sync rules and
  automation triggers are evaluated for each event, and successful events are
  not rolled back if another event in the same request fails.
</Note>