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

> ## Agent Instructions
> Install the Courier skill before writing code: `npx skills add trycourier/courier-skills`. It carries the verified SDK shapes and the rules you cannot get wrong.
> Authenticate every request with `Authorization: Bearer <API_KEY>`. A workspace has several environments and each has its own keys, which are plain `pk_` strings with no environment prefix. Start with Test.
> Send with `client.send.message`, the default import of the v7 Node SDK. Reference a template by its `nt_` id or its alias.
> A send accepts a bare Elemental element list, but storing content on a template requires the top-level elements wrapped in a channel element.
> Templates and journeys can be built in the Courier app or created through the API. Either way they live in the workspace and are referenced by ID when you send.
> The hosted MCP server is https://mcp.courier.com. For a briefing on what Courier is and when to use it, read https://www.courier.com/llms.txt.
> Prefer the Guides tab for how-do-I questions and the Docs tab for how-does-it-behave questions. The API reference lives under /api-reference.

# Sync events between Segment and Courier

> Send Segment identify and track events into Courier, and stream message events back.

export const Guide = ({href, children, name, bare}) => {
  const label = children || name || href;
  if (bare) {
    return <a href={href}>{label}</a>;
  }
  return <a className="cx-endpoint" data-kind="guide" href={href}>
      <span className="cx-endpoint-label">{label}</span>
      <span className="cx-endpoint-method">GUIDE</span>
    </a>;
};

export const Endpoint = ({method, path, name, href, children, bare}) => {
  const verb = String(method || "").toUpperCase();
  const title = verb + " " + path;
  const label = children || name || path;
  if (bare) {
    return href ? <a href={href}><code>{title}</code></a> : <code>{title}</code>;
  }
  if (!href) {
    return <span className="cx-endpoint" data-method={verb} title={title}>
        <span className="cx-endpoint-label">{label}</span>
        <span className="cx-endpoint-method">{verb}</span>
      </span>;
  }
  return <a className="cx-endpoint" data-method={verb} href={href} title={title}>
      <span className="cx-endpoint-label">{label}</span>
      <span className="cx-endpoint-method">{verb}</span>
    </a>;
};

export const AppLink = ({href, children, name, bare}) => {
  const label = children || name || "Open in Courier";
  if (bare) {
    return <a href={href} target="_blank" rel="noreferrer">{label}</a>;
  }
  return <a className="cx-endpoint" data-kind="app" href={href} target="_blank" rel="noreferrer">
      <span className="cx-endpoint-label">{label}</span>
      <span className="cx-endpoint-method" aria-hidden="true">↗</span>
    </a>;
};

## Segment to Courier

Courier's Segment destination sends data from your web or mobile app into Courier.

Events appear on the <AppLink href="https://app.courier.com/integrations/catalog/segment">Segment integration page</AppLink> in Courier Studio, where you map them to notification workflows. For example, an `analytics.identify` event can trigger an automation that welcomes a new user.

<Guide href="/docs/guides/notify-from-segment">Start a journey from Segment</Guide> walks that setup end to end.

**Supported Segment events:**

* `analytics.group`
* `analytics.identify`
* `analytics.track`

### Connecting Segment

<Steps>
  <Step title="Open the Segment Destinations catalog">
    In the Segment app, open the [Destinations](https://segment.com/docs/connections/destinations) catalog page.
  </Step>

  <Step title="Add a destination">
    Click **Add Destination**.
  </Step>

  <Step title="Select the Courier destination">
    Search the catalog for Courier and select the Courier destination.
  </Step>

  <Step title="Choose a source">
    Choose the Source that sends data to the Courier destination.
  </Step>

  <Step title="Get your Courier API Key">
    On the <AppLink href="https://app.courier.com/integrations">Courier Integrations Page</AppLink>, search for Segment and open it to get the Courier API Key. If no key is there, copy the Auth Token from the API Keys section of the <AppLink href="https://app.courier.com/settings">Courier Settings Page</AppLink>.
  </Step>

  <Step title="Enter the API Key in Segment">
    In Segment, enter the Courier API Key or Auth Token in the Courier destination's API Key field.
  </Step>

  <Step title="Validate the setup">
    Open the destination's "Event Tester" in Segment and click "Send Event" at the bottom of the page. In Courier Studio, refresh or wait a few seconds. The test event appears in the list if setup succeeded.
  </Step>
</Steps>

### Identify calls

Segment Identify calls connect a user to their actions (Segment events) and record traits about them.
Segment identifies the user by User ID, and the call can carry traits such as name and email.
Courier uses those traits to update recipient profiles over time. See the [Segment Identify spec](https://segment.com/docs/connections/spec/identify/) and <Endpoint method="GET" path="/profiles/{user_id}" name="Get a Profile" href="/docs/api-reference/user-profiles/get-a-profile">Courier Profiles API</Endpoint> for details.

Example payload

```json theme={null}
{
  "messageId": "segment-test-message-iskh4123",
  "timestamp": "2024-05-21T18:00:18.913Z",
  "type": "identify",
  "email": "sarah@acme-corp.com",
  "traits": {
    "trait1": 2,
    "email": "sarah@acme-corp.com"
  },
  "userId": "user_123"
}
```

### Track calls

Segment Track calls record actions your users perform, along with any properties on those actions. See the [Segment Track spec](https://segment.com/docs/connections/spec/track/) for details.

Track events appear in Courier with a `track/` prefix. Courier reads data from the track's `properties` object. Map track events to Courier journeys to send notifications from them.

An example Segment API call:

```javascript theme={null}
analytics.track('Login Button Clicked', {
  messageId: "segment-test-message-a8rmf",
  timestamp: "2021-12-07T08:41:59.410Z",
  type: "track",
  email: "sarah@acme-corp.com",
  projectId: "4GgKeBoVJkT9EZL4vAmduv",
  properties: {
    property1: 1,
    property2: "test",
    property3: true
  },
  userId: "user_123",
  event: "Segment Test Event Name"
})
```

Courier receives that call as a track event:

```json theme={null}
{
  "messageId": "segment-test-message-a8rmf",
  "timestamp": "2021-12-07T08:41:59.410Z",
  "type": "track",
  "email": "sarah@acme-corp.com",
  "projectId": "4GgKeBoVJkT9EZL4vAmduv",
  "properties": {
    "property1": 1,
    "property2": "test",
    "property3": true
  },
  "userId": "user_123",
  "event": "Segment Test Event Name"
}
```

Courier maps that object into its data object:

```json theme={null}
{
  "data": {
    "property1": 1,
    "property2": "test",
    "property3": true
  }
}
```

### Troubleshooting

A persistent "No Segment events received yet." message usually means Segment could not set up your Courier workspace as a destination. To get the test event through:

1. Confirm the API Key was copied into Segment exactly.
2. Check where the `email` property sits in Segment's test JSON object. On an identify call it belongs inside the `traits` object, not at the top level. Move it and resend the test event.
3. If it still fails, reach out to Courier Support.

***

## Courier to Segment

Configure Courier as a Segment Source, and Courier message and audience events flow back into Segment for analytics.

### Setting up Courier as a Segment source

<Steps>
  <Step title="Open the Sources page">
    In Segment, open the *Sources* page under "Connections".
  </Step>

  <Step title="Select your framework">
    Select your framework, for example Node.js.
  </Step>

  <Step title="Obtain a write key">
    Segment then shows instructions for adding it to that codebase. Copy the write key from this page.
  </Step>

  <Step title="Paste the write key into Courier">
    In Courier's Segment configuration, paste your [Segment Write Key](https://segment.com/docs/connections/find-writekey/) into the *Segment write key* field.
  </Step>
</Steps>

Courier starts sending updates to Segment once the write key is saved.

### Courier events sent to Segment

With Courier as a Segment source, Segment can track these events:

#### Message events

* `Message Clicked`
* `Message Delivered`
* `Message Opened`
* `Message Sent`
* `Message Undeliverable`
* `Message Unroutable`

#### Audience events

* `Audience User Matched`
* `Audience User Unmatched`

#### Preferences events

* `User Subscribed`
* `User Unsubscribed`