API Reference
Bulk Delete Messages
Overview
Delete multiple messages in a single request by sending an array of message IDs.
Use this endpoint for moderation cleanups, retention jobs, or admin tools that remove several messages at once. You can send between 1 and 100 valid IDs per call. The response reports how many messages were deleted.
When to use this endpoint?
Use Bulk Delete Messages when:
- Removing many messages selected in an admin or moderation UI.
- Running cleanup or retention jobs that delete batches of records.
- You have 1–100 valid message IDs and want one API round-trip.
- You need a summary count of how many messages were removed.
To delete a single message by path ID, use Delete Message instead.
{baseUrl}/api/{apiVersion}/client/messages/bulk-deleteAuthentication
Required (Bearer token)
Tenant-scoped
Yes (tenant DB — requires x-client-id)
Request Headers
| Header | Value | Description |
|---|---|---|
| is-tenant | true | Targets the tenant DB ("true", needs x-client-id). |
| x-client-id | {{clientId}} | Tenant (client) id. Uses the {{clientId}} variable. |
| Content-Type | application/json | — |
Request Payload
{
"messageIds": [
"{{messageId}}",
"6a2f94f49f5fc6c3073dcae9"
]
}Success Response (HTTP 200 OK)
On success, the API returns how many messages were deleted.
{
"success": true,
"message": "Messages deleted successfully",
"data": {
"messagesDeleted": 3
},
"error": null
}Error Responses
HTTP 400 Bad Request — Invalid ids
{
"success": false,
"message": "messageIds must be 1-100 valid ids",
"data": null,
"error": "messageIds must be 1-100 valid ids"
}Notes & Validation Rules
- messageIds must be 1-100 valid ids (HTTP 400 - Invalid ids)
Workflow
Follow this flow to remove multiple messages safely and refresh your UI from the deletion summary.
- 1
Select resources to remove
Collect 1–100 valid IDs from your admin UI or automation job.
- 2
Call the bulk-delete endpoint
Send the ID array in the request body with tenant headers and a Bearer token.
- 3
Review the deletion summary
Use the response counts to confirm how many records were removed and refresh your list views.
Common Errors
HTTP 200 OK means the bulk delete completed. The request fails when the ID list is empty, too large, or contains invalid IDs.
| Code | Reason |
|---|---|
| 400 Bad Request | messageIds must be 1–100 valid ids. |
| 401 Unauthorized | Access Token is missing, invalid, or expired. |
| 500 Internal Server Error | An unexpected error occurred while deleting messages. |
Best Practices
- Cap each request at 100 IDs — split larger sets into multiple calls.
- Validate ObjectIds in your UI before submitting the bulk-delete body.
- Use the returned
messagesDeletedcount to confirm the operation and refresh list views. - Require an explicit confirmation before bulk deletion — the action is irreversible.
- Always send Content-Type: application/json with tenant headers and a Bearer token over HTTPS.
Messages deleted
Review the deletion summary, then refresh List Messages so removed records no longer appear in your admin views.