The Segment API allows you to create, retrieve, manage, and delete dynamic contact segments for targeted messaging, automation workflows, and broadcast campaigns.

Segments help you group contacts based on filters, behavior, or engagement rules.

Base URL

https://api.dmly.io/api

Authentication

All endpoints require the x-api-key header:

x-api-key: YOUR_API_KEY

Endpoints

List / Search Segments

GET /v1/segments

Retrieve a list of segments with optional filtering and search.

Query Parameters

Example Request

curl -X GET "https://api.dmly.io/api/v1/segments?workspaceId=ws_123&page=1&limit=20" \
  -H "x-api-key: YOUR_API_KEY"

✅ Success Response 200 OK

[
  {
    "id": "seg_001",
    "name": "High Value Customers",
    "type": "dynamic",
    "status": "active",
    "segments": [],
    "retargetBroadcast": null,
    "retargetEngagementType": null,
    "scheduledDateTime": null,
    "startedAt": null,
    "completedAt": null
  }
]

2️⃣ Create a Segment

POST /v1/segments

Create a new segment.

Request Body

{
  "name": "Inactive Contacts",
  "type": "dynamic",
  "status": "active"
}

📥 Example Request

curl -X POST https://api.dmly.io/api/v1/segments \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
        "name": "Inactive Contacts",
        "type": "dynamic",
        "status": "active"
      }'

✅ Success Response 200 OK

{
  "id": "seg_002",
  "name": "Inactive Contacts",
  "type": "dynamic",
  "status": "active",
  "segments": [],
  "retargetBroadcast": null,
  "retargetEngagementType": null,
  "scheduledDateTime": null,
  "startedAt": null,
  "completedAt": null
}

3️⃣ Get Segment by ID

GET /v1/segments/{segmentId}

Retrieve a segment using its unique ID.

Path Parameters

Example Request

curl -X GET https://api.dmly.io/api/v1/segments/seg_002 \
  -H "x-api-key: YOUR_API_KEY"

✅ Success Response 200 OK

{
  "id": "seg_002",
  "name": "Inactive Contacts",
  "type": "dynamic",
  "status": "active",
  "segments": [],
  "retargetBroadcast": null,
  "retargetEngagementType": null,
  "scheduledDateTime": null,
  "startedAt": null,
  "completedAt": null
}

4️⃣ Delete Segment by ID

DELETE /v1/segments/{segmentId}

Delete a segment using its unique ID.

Path Parameters

Example Request

curl -X DELETE https://api.dmly.io/api/v1/segments/seg_002 \
  -H "x-api-key: YOUR_API_KEY"

✅ Success Response 200 OK

{
  "success": true
}

📦 Schemas

Segment Schema

{
  "id": "string",
  "name": "string",
  "type": "string",
  "status": "string",
  "segments": [
    {
      "id": "string"
    }
  ],
  "retargetBroadcast": {
    "id": "string"
  },
  "retargetEngagementType": "string",
  "scheduledDateTime": "string",
  "startedAt": "string",
  "completedAt": "string"
}

Segments Response Schema

[
  {
    // Segment object
  }
]

Delete Response Schema

{
  "success": true
}

⚙️ Best Practices

• Use pagination (page, limit) when listing segments.

• Store segment IDs securely for broadcast and automation usage.

• Avoid deleting segments currently attached to:

  • Broadcast campaigns

  • Automation workflows

• Validate API key usage on server-side integrations only.

• Monitor API rate limits.