The Broadcast API lets you trigger and manage bulk messaging campaigns in DMLY. Use it to create broadcasts, update campaign details, retrieve delivery logs, and manage existing broadcasts.

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 Broadcasts

GET /v1/broadcasts

Retrieve a list of broadcasts with optional filtering and search.

Response: 200 OK — Array of BroadcastResponse

Query Parameters

Example Request

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

✅ Example Response

[
  {
    "workspace": { "id": "ws_123" },
    "name": "February Promo",
    "type": "whatsapp"
  }
]

2️⃣ Create a Broadcast

POST /v1/broadcasts

Create a new broadcast campaign.

Request Body: BroadcastRequest (application/json)
Response: 200 OK — BroadcastResponse

Example Request

curl -X POST "https://api.dmly.io/api/v1/broadcasts" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
        "workspace": { "id": "ws_123" },
        "name": "New Launch Broadcast",
        "type": "whatsapp"
      }'

✅ Example Response

{
  "workspace": { "id": "ws_123" },
  "name": "New Launch Broadcast",
  "type": "whatsapp"
}

3️⃣ Get Broadcast by ID

GET /v1/broadcasts/{broadcastId}

Retrieve a broadcast by its unique ID.

Response: 200 OK — BroadcastResponse

Path Parameters

Example Request

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

✅ Example Response

{
  "workspace": { "id": "ws_123" },
  "name": "February Promo",
  "type": "whatsapp"
}

4️⃣ Update Broadcast by ID

PUT /v1/broadcasts/{broadcastId}

Update an existing broadcast by its unique ID.

Request Body: BroadcastRequest (application/json)
Response: 200 OK — BroadcastResponse

Path Parameters

Example Request

curl -X PUT "https://api.dmly.io/api/v1/broadcasts/bc_001" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
        "workspace": { "id": "ws_123" },
        "name": "February Promo (Updated)",
        "type": "whatsapp"
      }'

✅ Example Response

{
  "workspace": { "id": "ws_123" },
  "name": "February Promo (Updated)",
  "type": "whatsapp"
}

5️⃣ Delete Broadcast by ID

DELETE /v1/broadcasts/{broadcastId}

Delete a broadcast by its unique ID.

Response: 200 OK — DeleteResponse

Path Parameters

Example Request

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

✅ Example Response

{
  "success": true
}

6️⃣ Get Broadcast Logs

GET /v1/broadcasts/{broadcastId}/logs

Retrieve logs for a specific broadcast (delivery results per recipient).

Response: 200 OK — Array of BroadcastLog

Path Parameters

Query Parameters

Example Request

curl -X GET "https://api.dmly.io/api/v1/broadcasts/bc_001/logs?page=1&limit=50" \
  -H "x-api-key: YOUR_API_KEY"

✅ Example Response

[
  {
    "broadcast": { "id": "bc_001", "name": "February Promo" },
    "recipientName": "John Doe",
    "countryCode": "ng",
    "phone": "2348012345678",
    "status": "SENT",
    "reply": "",
    "error": "",
    "createdAt": "2026-02-20T10:00:00.000Z",
    "updatedAt": "2026-02-20T10:05:00.000Z"
  }
]

📦 Schemas

BroadcastRequest Schema

{
  "workspace": { "id": "string" },
  "name": "string",
  "type": "string"
}

BroadcastResponse Schema

{
  "workspace": { "id": "string" },
  "name": "string",
  "type": "string"
}

BroadcastLog Schema

{
  "broadcast": { "id": "string", "name": "string" },
  "recipientName": "string",
  "countryCode": "string",
  "phone": "string",
  "status": "string",
  "reply": "string",
  "error": "string",
  "createdAt": "string",
  "updatedAt": "string"
}

BroadcastResponses Schema

[
  {
    // BroadcastResponse object
  }
]

DeleteResponse Schema

{
  "success": true
}

✅ Best Practices

• Use workspaceId when listing broadcasts for multi-workspace integrations.

• Paginate broadcast logs (page, limit) for large campaigns.

• Store broadcastId immediately after creation for future updates and log retrieval.

• Use the Logs endpoint to track:

  • Sent vs failed recipients

  • Errors returned per recipient

  • Replies captured (if supported by your workflow)

Security Notes

• Never expose x-api-key in frontend code.

• Validate broadcast ownership by workspace in your integration.

• Log all create/update/delete operations for auditing.