TextKitDocs

Delete a message

Deletes a finished message (delivered, failed, received, or sent with receipt_status: "missing") and every copy of its text: the events about it, pending webhook retries, the request logs that carried it, and the conversation preview.

DELETE/v1/messages/{id}

Path Parameters

  • idstringrequired

Details

Opt-out and consent records, usage and billing are kept, and a batch's results keep the message's outcome. Queued messages are refused (409 invalid_state): cancel a scheduled one with DELETE /scheduled_messages/{id}.

Also refused: blocked messages, a message that is the proof of an opt-out or opt-in, and messages from a registration our team is reviewing. Recorded in the audit log as message.deleted.

A key deletes only its own mode's messages.

Responses

  • 200JSON object

    Deleted

  • 401Error

    Missing, malformed, or revoked API key

  • 402Error

    Billable live calls only: the prepaid credit balance cannot cover the call (insufficient_credits); nothing was done or charged

  • 404Error

    Not found

  • 409Error

    Not finished, blocked, consent evidence, or under review

  • 429Error

    Rate limit or quota exceeded

Response Fields

  • idstring
  • objectmessage
  • deletedboolean

Errors

Every error has the same JSON shape, and request_id matches the X-Request-Id response header. Errors lists every code and what to do about it.

  • 401

    Missing, malformed, or revoked API key

  • 402

    Billable live calls only: the prepaid credit balance cannot cover the call (insufficient_credits); nothing was done or charged

  • 404

    Not found

  • 409

    Not finished, blocked, consent evidence, or under review

  • 429

    Rate limit or quota exceeded