Batch delete messages

Permanently deletes multiple SMS messages in a single batch request (up to 100 message IDs) and returns the individual deletion outcome (success: true, or success: false with an error object) for each requested ID. 

POST /api/v2/messages:batchDelete

Table of contents

Endpoint summary

Property Value
HTTP method POST
Endpoint path /api/v2/messages:batchDelete
Authentication Authorization: Bearer <api_key> or Authorization: Basic <base64(username:password)>
Content-Type application/json
Success status code 200 OK

Note: Missing message IDs do not cause the entire batch request to fail. Instead, the endpoint returns 200 OK and reports individual deletion outcomes per ID in the results array. Each located message is permanently removed from whichever folder (inbox, outbox, postponed, sent, notsent, deleted) holds it.

Request

Request headers

Header Required Description
Authorization Yes Credentials identifying the user account context (Bearer <api_key> or Basic <credentials>).
Content-Type Yes Must be application/json.

Request body

The request body must be a JSON object with strictly case-sensitive camelCase property names.

Parameters (BatchDeleteRequest)

Field Type Required Description
messageIds string (UUID)[] Yes Non-empty array of message identifiers to delete (minimum 1, maximum 100 non-empty strings).

Response

200 OK

Returns a BatchDeleteResponse object containing the ordered results array corresponding 1-to-1 with the requested messageIds.

Root object (BatchDeleteResponse)

Field Type Description
results object[] (BatchDeleteResultItem[]) Array of individual deletion outcomes in the exact order of messageIds.

results[] item object (BatchDeleteResultItem)

Field Type Presence Description
messageId string (UUID) Always The message identifier targeted for deletion.
success boolean Always true if the message was found and permanently deleted; false if not found.
error object (ApiErrorDetail) When success is false Structured error details explaining why deletion failed (e.g., 404 Not Found). Omitted when success is true.

error object (ApiErrorDetail)

Field Type Description
code integer HTTP status code for the item failure (e.g., 404).
description string Explanation of why the specific message could not be deleted.
action string Recommended action to resolve the item error.
timestamp string (ISO 8601) Timestamp when the error was evaluated.

Error responses

When authentication fails, the JSON body is malformed, or request-level validation fails (such as an empty messageIds array, more than 100 IDs, or a blank ID element), the API returns a top-level ApiErrorResponse object.

Common error status codes:

Status code Condition Description
401 Unauthorized Missing or invalid credentials Authentication credentials were not provided or could not be resolved to an active user.
422 Unprocessable Entity Request validation error messageIds is missing, empty, exceeds 100 items, or contains a null/whitespace ID.

Error schema (ApiErrorResponse):

Field Type Description
error.code integer HTTP status code (e.g., 401, 422).
error.description string Explanation of the specific error condition.
error.action string Recommended action to resolve the error.
error.timestamp string (ISO 8601) Timestamp when the error occurred.

Examples

1. Batch delete messages with partial failure

Attempts to delete two messages: the first ID is found and deleted ("success": true), while the second ID does not exist and returns an inline 404 item error ("success": false).

Request headers: 

POST /api/v2/messages:batchDelete HTTP/1.1
Host: localhost:9509
Authorization: Bearer <api_key>
Content-Type: application/json

Request body: 

{
  "messageIds": [
    "26385eed-6a6c-4deb-b549-dc055211a71d",
    "8f3b2a1c-9d4e-4f5a-b6c7-1a2b3c4d5e6f"
  ]
}

Response (200 OK): 

{
  "results": [
    {
      "messageId": "26385eed-6a6c-4deb-b549-dc055211a71d",
      "success": true
    },
    {
      "messageId": "8f3b2a1c-9d4e-4f5a-b6c7-1a2b3c4d5e6f",
      "success": false,
      "error": {
        "code": 404,
        "description": "Message with ID '8f3b2a1c-9d4e-4f5a-b6c7-1a2b3c4d5e6f' was not found.",
        "action": "Verify that message ID '8f3b2a1c-9d4e-4f5a-b6c7-1a2b3c4d5e6f' exists and was dispatched by the current user.",
        "timestamp": "2026-10-21T10:21:00+02:00"
      }
    }
  ]
}

2. Batch delete multiple messages (all successful)

Deletes two existing messages in a single request where all items succeed.

Request headers: 

POST /api/v2/messages:batchDelete HTTP/1.1
Host: localhost:9509
Authorization: Bearer <api_key>
Content-Type: application/json

Request body: 

{
  "messageIds": [
    "26385eed-6a6c-4deb-b549-dc055211a71d",
    "b1c2d3e4-f5a6-7b8c-9d0e-1f2a3b4c5d6e"
  ]
}

Response (200 OK): 

{
  "results": [
    {
      "messageId": "26385eed-6a6c-4deb-b549-dc055211a71d",
      "success": true
    },
    {
      "messageId": "b1c2d3e4-f5a6-7b8c-9d0e-1f2a3b4c5d6e",
      "success": true
    }
  ]
}

3. Error: Empty messageIds array (422 Unprocessable Entity)

Returned when messageIds is missing or contains no items.

Response (422 Unprocessable Entity): 

{
  "error": {
    "code": 422,
    "description": "The 'messageIds' array is required and must contain at least one item.",
    "action": "Provide a non-empty array of message IDs (up to 100).",
    "timestamp": "2026-10-21T10:21:00+02:00"
  }
}

4. Error: Exceeding maximum batch size (422 Unprocessable Entity)

Returned when messageIds contains more than the maximum allowed limit of 100 items.

Response (422 Unprocessable Entity): 

{
  "error": {
    "code": 422,
    "description": "The 'messageIds' array cannot contain more than 100 items.",
    "action": "Reduce the number of message IDs to at most 100 items.",
    "timestamp": "2026-10-21T10:21:00+02:00"
  }
}

More information