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

# Segment Integration

> Stream Segment track and identify calls into Sequenzy to trigger email automations

Connect Segment to stream your existing analytics events into Sequenzy. Track calls become events you can trigger automations on, and identify calls keep subscriber profiles up to date - all one-way, without changing your instrumentation.

## What is Segment?

[Segment](https://segment.com) is a customer data platform (CDP) that collects events from your product once and routes them to your downstream tools. If you already send `analytics.track()` and `analytics.identify()` calls, Sequenzy becomes one more destination.

## Prerequisites

Sequenzy matches events to subscribers by email, so your identify calls need an email trait:

```javascript theme={null}
// When a user logs in, identify them with their email
analytics.identify(userId, {
  email: "user@example.com",
  firstName: "John",
  plan: "pro",
});
```

<Warning>
  Identifying once is enough: the identify call stores the `userId` and
  `anonymousId` on the subscriber, and later track, page, and screen calls that
  carry only one of those identifiers are matched back to the same subscriber.
  Purely anonymous events (never identified, no email anywhere) are
  automatically skipped.
</Warning>

## Connecting Segment

### Step 1: Get Your Webhook Configuration

1. Go to **Settings → Integrations** in Sequenzy
2. Find **Segment** under Product Analytics
3. Click **Connect**
4. Copy the **Webhook URL** and choose a **Shared Secret** (at least 16 characters)

### Step 2: Add a Webhooks Destination in Segment

1. In your [Segment workspace](https://app.segment.com), open **Catalog → Destinations**
2. Search for **"Webhooks (Actions)"** and add it to the source you want to stream
3. Configure the destination:
   * **URL**: Paste your Sequenzy webhook URL
   * **Shared Secret**: Enter the same secret you chose in Step 1
4. Enable mappings for the **Track** and **Identify** calls you want to send (Send as JSON, POST)
5. Leave **Batch Size** set to `0` so every signed request contains one message
6. Enable the destination

### Step 3: Complete Connection in Sequenzy

1. Return to Sequenzy's Segment connection modal
2. Enter the same shared secret
3. Click **Connect Segment**

That's it! Segment calls will now flow into Sequenzy. Deliveries are verified against the shared secret, and duplicate deliveries are deduplicated by Segment's own `messageId`.

<Warning>
  Keep batching disabled in Segment. Webhooks (Actions) signs only the first
  item of a batched delivery, so later items are not protected against
  tampering. Sequenzy requires the signature to cover the complete request and
  rejects Segment's first-item-only batch signature.
</Warning>

## What Gets Synced

| Segment call | What Sequenzy does                                                                           |
| ------------ | -------------------------------------------------------------------------------------------- |
| `track`      | Records `product.<event>` on the matched subscriber and triggers automations                 |
| `identify`   | Creates or updates the subscriber from traits, then records `product.identify`               |
| `page`       | Records `product.page` - skipped by default on new connections (see below)                   |
| `screen`     | Records `product.screen` - skipped by default on new connections                             |
| `group`      | Acknowledged but never creates a subscriber (group traits describe an account, not a person) |
| `alias`      | Acknowledged but never creates a subscriber or event                                         |

When an event is received, Sequenzy:

1. Checks for an email in the event `properties`, or in `context.traits` for identified calls (identify calls use their `traits`)
2. If there is no email, matches the event's `userId` or `anonymousId` against the `segmentUserId` / `segmentAnonymousId` attributes stored by an earlier identify call - **only events that resolve neither way are skipped**
3. Creates or updates the subscriber (an identify reporting a new email for a known `userId` updates the existing subscriber's email instead of creating a duplicate)
4. Records the event with the `product.` prefix (e.g., `product.Order Completed`, `product.feature_used`)
5. Triggers any automations listening for that event

### Event Naming

Segment track events are prefixed with `product.` in Sequenzy, keeping the event name verbatim:

| Segment call                         | Sequenzy Event            |
| ------------------------------------ | ------------------------- |
| `analytics.track("Order Completed")` | `product.Order Completed` |
| `analytics.track("feature_used")`    | `product.feature_used`    |
| `analytics.identify(...)`            | `product.identify`        |
| `analytics.page(...)`                | `product.page`            |

<Note>
  Segment and PostHog feed the same `product.*` namespace, so sequences built on
  `product.*` events keep working if you switch analytics providers.
</Note>

### Synced Attributes

Only `identify` calls update subscriber attributes. Properties on all other calls stay on the event (available to automations and event-based segments) and are never copied onto the subscriber profile:

| Attribute            | Source                                                                           |
| -------------------- | -------------------------------------------------------------------------------- |
| `segmentUserId`      | The `userId` on the identify call                                                |
| `segmentAnonymousId` | The `anonymousId` on the identify call, so pre-login events resolve too          |
| First / last name    | `firstName`/`lastName` traits, or a single `name` trait split on the first space |
| Custom attributes    | Primitive (string, number, boolean) identify traits                              |

Credential-looking trait keys (`token`, `password`, `apiKey`, and similar) are always redacted before storage, and nested objects are not synced as attributes.

## Importing Event History (Optional)

A fresh connection only receives events from the moment the webhook goes live. If you use [Segment Unify](https://segment.com/docs/unify/), you can also backfill your existing contacts' recent event history so event-based segments reflect the last two weeks of activity immediately. Segment's Profile API serves at most the last 14 days of a profile's events, so that is the window the import covers - older history is not available from Segment.

Segment has no bulk event export, so the import works through the [Profile API](https://segment.com/docs/unify/profile-api/): Sequenzy walks your existing contacts and reads each one's profile history (last 14 days) by email. Contacts without a Unify profile are simply skipped, and imported events dedupe against live webhook deliveries by `messageId`, so the overlap window cannot double-count.

<Note>
  Historical events never start automations, never send emails, and never fire
  outbound webhooks. They appear on the contact timeline and count toward
  event-based segments, and a contact's signup date moves earlier when history
  proves they predate it.
</Note>

To set it up:

1. In Segment, go to **Unify → Settings → API access** and note the **Space ID**, then generate a **Profile API token**
2. In Sequenzy's Segment connection modal, check **Import event history** and enter both - the workspace region (US or EU) is detected automatically
3. Connect. The import runs in the background; the Segment card shows its progress and offers **Retry** if it fails

From the CLI:

```bash theme={null}
sequenzy integrations connect segment \
  --webhook-secret my_shared_secret \
  --history-region us \
  --history-space-id spa_abc123 \
  --history-api-key profile_api_token
```

A failed or interrupted import can be re-run at any time with `sequenzy integrations sync <integration-id>` (or the dashboard's Retry button). Re-runs restart from the beginning and already-imported events dedupe, so nothing is duplicated.

## Page and Screen Calls

Connections created from August 2026 on skip `page` and `screen` calls by default because their volume usually drowns out the events you automate on - `identify` always passes so profile updates keep working. To ingest them, add `page` or `screen` to your event allowlist and make sure their mappings are enabled on the Segment destination (Segment only delivers calls whose mappings are on). If you never want them, disable their mappings in Segment instead - that also keeps them out of your Segment delivery volume.

## Event Allowlist (Optional)

To sync only specific events, connect via the API, CLI, or MCP with an allowlist:

```bash theme={null}
sequenzy integrations connect segment \
  --webhook-secret my_shared_secret \
  --event-allowlist "Order Completed" "signed_up"
```

`identify` calls always pass, even when they are not on the allowlist - they carry the profile updates that keep every other event resolvable.

Or filter at the source: Segment's destination filters and mapping triggers control which calls are delivered at all, which also keeps them out of your Segment delivery volume.

## Using with Automations

### Activation Sequence

1. Go to **Automations** → **Create New**
2. Set trigger to **Event Received** → `product.signed_up`
3. Add a **Wait** step: 3 days
4. Add a **Condition**: Check if `product.feature_used` was NOT received
5. Send a "Did you know about this feature?" email

### Re-engagement for Inactive Users

1. Create a segment: "No `product.` events in last 14 days"
2. Send a re-engagement campaign to this segment

## Troubleshooting

### Events Not Appearing

1. Verify the destination URL in Segment matches your Sequenzy webhook URL exactly
2. Check that the destination's **Shared Secret** matches the secret you entered in Sequenzy - mismatches are rejected with a 401 and show up as failed deliveries in **Settings → Integrations → Activity**
3. **Most common issue**: Events don't carry an email - call `analytics.identify()` with the user's email when they log in

### Subscriber Not Created

Events that resolve neither an email nor a previously identified `userId` are silently skipped. Ensure:

1. You're calling `analytics.identify(userId, { email: "..." })` when users log in
2. The email is in `traits.email` (identify), `properties.email`, or `context.traits.email`
3. The email is a valid format

### Missing Subscriber Attributes

Subscriber attributes are updated only by `identify` calls. If an attribute isn't appearing, set it as an identify trait; properties on track calls never update the profile. Nested objects and credential-looking keys are excluded.

## FAQ

<AccordionGroup>
  <Accordion title="Is this one-way or two-way?">
    One-way: Sequenzy ingests events from Segment and never writes anything
    back. Sequenzy is a destination, not a source.
  </Accordion>

  <Accordion title="Which Segment plan do I need?">
    The Webhooks (Actions) destination is available on all Segment plans,
    including the free tier.
  </Accordion>

  <Accordion title="Can I send events from multiple Segment sources?">
    Yes. Add the same Webhooks destination (same URL and shared secret) to each
    source you want to stream.
  </Accordion>

  <Accordion title="What happens to events without email addresses?">
    Once a user has been identified with an email, later events that carry only
    their `userId` or `anonymousId` are matched back to the same subscriber.
    Events from users who were never identified (and carry no email anywhere) are
    silently skipped - Sequenzy needs an email or a known identifier to match a
    subscriber.
  </Accordion>

  <Accordion title="Will retried Segment deliveries duplicate events?">
    No. Deliveries are deduplicated by Segment's `messageId`, so a retry of the
    same message is acknowledged without creating a second event.
  </Accordion>

  <Accordion title="Is there a delay in event processing?">
    Events are processed in real-time. Most events appear in Sequenzy within
    seconds of being delivered by Segment.
  </Accordion>

  <Accordion title="Is this included in my plan?">
    Yes, the Segment integration is included at no extra cost.
  </Accordion>
</AccordionGroup>