Create segment method

Author: danrowden

README.md

@@ -116,6 +116,7 @@ You can use custom contact properties in API calls. Please make sure to [add cus
 - [listDedicatedSendingIps()](#listdedicatedsendingips)
 - [listAudienceSegments()](#listaudiencesegments)
 - [getAudienceSegment()](#getaudiencesegment)
+- [createAudienceSegment()](#createaudiencesegment)
 - [listThemes()](#listthemes)
 - [getTheme()](#gettheme)
 - [createTheme()](#createtheme)
@@ -2027,6 +2028,64 @@ const resp = await loops.getAudienceSegment("clr4c8t0v008yl70x3y4z5a6b");
 
 ---
 
+### createAudienceSegment()
+
+Create a new audience segment.
+[API Reference](https://loops.so/docs/api-reference/create-audience-segment)
+
+#### Parameters
+
+| Name | Type | Required | Notes |
+| ---- | ---- | -------- | ----- |
+| `name` | string | Yes | The name of the audience segment. Must be unique within the team. |
+| `description` | string | No | An optional description of the audience segment. |
+| `filter` | object | Yes | A tree of audience conditions combined with `match` (`all` or `any`). |
+
+#### Example
+
+```javascript
+const resp = await loops.createAudienceSegment({
+  name: "Active users",
+  description: "Contacts who opened a recent campaign",
+  filter: {
+    match: "all",
+    conditions: [
+      {
+        type: "property",
+        key: "planName",
+        operator: "equals",
+        value: "pro",
+      },
+    ],
+  },
+});
+```
+
+#### Response
+
+```json
+{
+  "id": "cls6e8g0i2k4m6o8q0s2u4w6",
+  "name": "Active users",
+  "description": "Contacts who opened a recent campaign",
+  "createdAt": "2025-06-29T07:47:39.370Z",
+  "updatedAt": "2025-06-29T07:47:39.370Z",
+  "filter": {
+    "match": "all",
+    "conditions": [
+      {
+        "type": "property",
+        "key": "planName",
+        "operator": "equals",
+        "value": "pro"
+      }
+    ]
+  }
+}
+```
+
+---
+
 ### listCampaignGroups()
 
 Retrieve a paginated list of campaign groups.
@@ -2968,6 +3027,7 @@ const resp = await loops.completeUpload("clu7f1w3y011yl70m5n6o7p8q");
   - Added event patterns ([`listEventPatterns()`](#listeventpatterns), [`getEventPattern()`](#geteventpattern), [`getEventPatternByName()`](#geteventpatternbyname)).
   - Expanded workflows with create/update/mutate APIs ([`createWorkflow()`](#createworkflow), [`updateWorkflow()`](#updateworkflow), [`changeWorkflowMailingList()`](#changeworkflowmailinglist), [`createWorkflowNode()`](#createworkflownode), [`updateWorkflowNode()`](#updateworkflownode), [`deleteWorkflowNode()`](#deleteworkflownode), [`addWorkflowBranch()`](#addworkflowbranch), [`deleteWorkflowNodesRecursive()`](#deleteworkflownodesrecursive)).
   - Added theme and component write APIs ([`createTheme()`](#createtheme), [`updateTheme()`](#updatetheme), [`createComponent()`](#createcomponent), [`updateComponent()`](#updatecomponent)).
+  - Added [`createAudienceSegment()`](#createaudiencesegment).
   - Added [`runEmailMessageGuardian()`](#runemailmessageguardian).
   - Aligned workflow response types with the API (`status`, nullable `workflowRevisionId`; removed unused `emoji`).
 - `v7.0.0` (Jun 24, 2026)

src/__tests__/LoopsClient.test.ts

@@ -1116,6 +1116,130 @@ describe("LoopsClient", () => {
     });
   });
 
+  describe("createAudienceSegment", () => {
+    it("should create an audience segment", async () => {
+      const filter = {
+        match: "all" as const,
+        conditions: [
+          {
+            type: "property" as const,
+            key: "planName",
+            operator: "equals" as const,
+            value: "pro",
+          },
+        ],
+      };
+      const mockResponse = {
+        id: "cls6e8g0i2k4m6o8q0s2u4w6",
+        name: "Active users",
+        description: "Contacts on the pro plan",
+        createdAt: "2025-06-29T07:47:39.370Z",
+        updatedAt: "2025-06-29T07:47:39.370Z",
+        filter,
+      };
+
+      global.fetch = jest.fn().mockResolvedValue({
+        ok: true,
+        text: () => Promise.resolve(JSON.stringify(mockResponse)),
+      });
+
+      const result = await client.createAudienceSegment({
+        name: "Active users",
+        description: "Contacts on the pro plan",
+        filter,
+      });
+
+      expect(result).toEqual(mockResponse);
+      expect(fetch).toHaveBeenCalledWith(
+        expect.stringContaining("v1/audience-segments"),
+        expect.objectContaining({
+          method: "POST",
+          body: JSON.stringify({
+            name: "Active users",
+            filter,
+            description: "Contacts on the pro plan",
+          }),
+        })
+      );
+    });
+
+    it("should handle error when segment name already exists", async () => {
+      const filter = {
+        match: "all" as const,
+        conditions: [
+          {
+            type: "property" as const,
+            key: "planName",
+            operator: "equals" as const,
+            value: "pro",
+          },
+        ],
+      };
+      const mockResponse = {
+        message: "An audience segment with this name already exists",
+      };
+
+      global.fetch = jest.fn().mockResolvedValue({
+        ok: false,
+        status: 400,
+        text: () => Promise.resolve(JSON.stringify(mockResponse)),
+      });
+
+      await expect(
+        client.createAudienceSegment({
+          name: "Active users",
+          filter,
+        })
+      ).rejects.toThrow(APIError);
+
+      expect(fetch).toHaveBeenCalledWith(
+        expect.stringContaining("v1/audience-segments"),
+        expect.objectContaining({
+          method: "POST",
+          body: JSON.stringify({
+            name: "Active users",
+            filter,
+          }),
+        })
+      );
+    });
+
+    it("should handle error for an invalid filter", async () => {
+      const filter = {
+        match: "all" as const,
+        conditions: [
+          {
+            type: "property" as const,
+            key: "planName",
+            operator: "equals" as const,
+            value: "pro",
+          },
+        ],
+      };
+      const mockResponse = {
+        message: "Invalid filter",
+      };
+
+      global.fetch = jest.fn().mockResolvedValue({
+        ok: false,
+        status: 400,
+        text: () => Promise.resolve(JSON.stringify(mockResponse)),
+      });
+
+      try {
+        await client.createAudienceSegment({
+          name: "Active users",
+          filter,
+        });
+        fail("Should have thrown");
+      } catch (error) {
+        expect(error).toBeInstanceOf(APIError);
+        expect((error as APIError).statusCode).toBe(400);
+        expect((error as APIError).json).toEqual(mockResponse);
+      }
+    });
+  });
+
   describe("listThemes", () => {
     it("should list themes with pagination", async () => {
       const mockResponse = {

src/index.ts

@@ -1540,6 +1540,40 @@ class LoopsClient {
     });
   }
 
+  /**
+   * Create an audience segment.
+   *
+   * @param {Object} params
+   * @param {string} params.name The name of the audience segment. Must be unique within the team.
+   * @param {string} [params.description] An optional description of the audience segment.
+   * @param {AudienceFilter} params.filter A tree of audience conditions combined with `match`.
+   *
+   * @see https://loops.so/docs/api-reference/create-audience-segment
+   *
+   * @returns {Object} Created audience segment (JSON)
+   */
+  async createAudienceSegment({
+    name,
+    description,
+    filter,
+  }: {
+    name: string;
+    description?: string;
+    filter: AudienceFilter;
+  }): Promise<AudienceSegment> {
+    const payload: {
+      name: string;
+      description?: string;
+      filter: AudienceFilter;
+    } = { name, filter };
+    if (description !== undefined) payload.description = description;
+    return this._makeQuery({
+      path: "v1/audience-segments",
+      method: "POST",
+      payload,
+    });
+  }
+
   /**
    * List email themes.
    *

tsconfig.json

@@ -4,7 +4,8 @@
     "noUnusedLocals": true,
     "noUnusedParameters": true,
     "strict": true,
-    "target": "ESNext"
+    "target": "ESNext",
+    "types": ["jest", "node"]
   },
   "include": ["./src/**/*.ts"]
 }