Segment API

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.

VIDEO GUIDE:

🔗 Base URL

https://api.dmly.io/rest

🔐 Authentication

All endpoints require the x-api-key header:

x-api-key: YOUR_API_KEY

📌 Endpoints

1⃣ 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/rest/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/rest/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/rest/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/rest/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.