> ## 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 Event

> Trigger an event for a subscriber

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

<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="event" type="string" required>
  Event name (e.g., `purchase_completed`, `saas.purchase`)
</ParamField>

<ParamField body="properties" type="object">
  Event properties/metadata. Can contain any key-value data.
</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" \
  -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"
    }
  }'
```

## 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

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

## 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

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "subscriber": {
      "id": "sub_abc123",
      "email": "user@example.com",
      "externalId": "user_123",
      "created": false
    },
    "event": {
      "id": "evt_xyz789",
      "name": "purchase_completed",
      "definitionCreated": false
    }
  }
  ```

  ```json 200 (new subscriber, double opt-in enabled) theme={null}
  {
    "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
    }
  }
  ```

  ```json 200 (event recorded, side effects failed) theme={null}
  {
    "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"]
  }
  ```

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

  ```json 409 theme={null}
  {
    "success": false,
    "error": "Subscriber identity conflict: email and externalId point to different subscribers."
  }
  ```

  ```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                                                                                           |
| `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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
# 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" }'
```

<Note>
  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.
</Note>