# stensul-apply-segment-set

> Applies an existing Segment Set to a module (or one element) and can write each segment's content in the same call.

Source: https://stensul.com/developers/reference/stensul-apply-segment-set/ · From the live server's tool list, 2026-09-28

- Scope: `dynamic-content:write`
- Access: write

Segments are matched by name or id. Segments you leave out keep the seed content; write them later with `stensul-update-segment-content`. The audiences and their logic are defined by an admin in Stensul and can't be changed here.

## Inputs

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `emailId` | string (24-char hex id) | yes | Email ID. |
| `libraryId` | string | no | Library the email belongs to. |
| `moduleInstanceId` | integer | yes | Module instance to make dynamic. |
| `segmentSetId` | string | yes | Segment Set to apply. |
| `elementInstanceId` | integer | no | One element instead of the whole module. |
| `segments` | array | no | `[{ segment, isHiddenSegment?, elements?: [{ elementInstanceId, elementType, content?, imageContent?, link?, style?, visibility? }] }]`. |

## Example request

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "stensul-apply-segment-set",
    "arguments": {
      "emailId": "64f0c0ffee0000000000abcd",
      "moduleInstanceId": 2817002,
      "segmentSetId": "seg_loyalty_tier",
      "segments": [
        {
          "segment": "Gold",
          "elements": [
            {
              "elementInstanceId": 3,
              "elementType": "text",
              "content": [
                {
                  "type": "paragraph",
                  "content": [
                    {
                      "text": {
                        "content": "Gold members get free shipping on the Autumn blend."
                      }
                    }
                  ]
                }
              ]
            }
          ]
        },
        {
          "segment": "Everyone else",
          "elements": [
            {
              "elementInstanceId": 3,
              "elementType": "text",
              "content": [
                {
                  "type": "paragraph",
                  "content": [
                    {
                      "text": {
                        "content": "Free shipping on orders over $40."
                      }
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  }
}
```

## Response

The resulting segments (`dynamicElementId`, `segmentId`, `segmentName`) and, per written segment, what was applied and any template warnings.

## Errors

| Status | Message | Cause | Fix |
| --- | --- | --- | --- |
| 401 | Authentication expired or missing | The session's authorization expired. | Sign in again when the host prompts. On a 401 or 403, the server's instructions tell the model to re-check sign-in first. |
| 403 | Insufficient OAuth scope (403): The token lacks the required scope | The API connection doesn't have the scope this tool needs. | An admin adds the scope to the API connection. Then sign in again: adding a scope revokes existing tokens. |
| 403 | API error (403): Action is unauthorized. | The signed-in user's role lacks the permission, for example `edit_campaign`. | Grant the permission to the user's role in Admin > Users & Roles. It works for other users on the same connection. |
| declined | Content declined by a guardrail | A value is outside what the template allows: an off-palette color, a size out of range, locked text. | Keep the value within the guardrail or make no change. Guardrails are enforced by Stensul and cannot be overridden from a chat. |