Delete a message

Permanently removes a single SMS message (inbound or outbound) identified by {messageId} from the authenticated user account's message folders. 

DELETE /api/v2/messages/{messageId}

Table of contents

Endpoint summary

Property Value
HTTP method DELETE
Endpoint path /api/v2/messages/{messageId}
Authentication Authorization: Bearer <api_key> or Authorization: Basic <base64(username:password)>
Success status code 204 No Content

Note: This endpoint searches across all folders (inbox, outbox, postponed, sent, notsent, deleted) and permanently removes the message from whichever queue holds it. If the message is still awaiting dispatch in outbox or postponed, deleting it cancels its pending delivery.

Request

Request headers

Header Required Description
Authorization Yes Credentials identifying the user account context (Bearer <api_key> or Basic <credentials>).

Path parameters

Parameter Type Required Description
messageId string (UUID) Yes Unique identifier of the message to delete.

Response

204 No Content

The message was found and permanently deleted. No response body is returned.

Error responses

When authentication fails or no message matching {messageId} exists for the authenticated user account, the API returns a structured 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.
404 Not Found Message not found No message matching {messageId} exists across any folder for the authenticated user account.

Error schema (ApiErrorResponse):

Field Type Description
error.code integer HTTP status code (e.g., 401, 404).
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. Delete a message by ID

Permanently deletes the message with ID 26385eed-6a6c-4deb-b549-dc055211a71d.

Request: 

DELETE /api/v2/messages/26385eed-6a6c-4deb-b549-dc055211a71d HTTP/1.1
Host: localhost:9509
Authorization: Bearer <api_key>

Response (204 No Content): 

HTTP/1.1 204 No Content

(Empty response body)

2. Error: Message not found (404 Not Found)

Returned when the requested message ID does not exist in any folder for the authenticated user.

Response (404 Not Found): 

{
  "error": {
    "code": 404,
    "description": "Message with ID '26385eed-0000-0000-0000-000000000000' was not found.",
    "action": "Verify that message ID '26385eed-0000-0000-0000-000000000000' exists and was dispatched by the current user.",
    "timestamp": "2026-10-21T10:21:00+02:00"
  }
}

More information