Skip to main content

​
Overview

Permanently deletes a message from the specified mailbox. The message is marked with the \Deleted flag and immediately expunged from the mailbox. This operation is irreversible and the message cannot be recovered.
This tool requires MAIL_IMAP_WRITE_ENABLED=true to be set in your environment variables. Write operations are disabled by default as a safety measure.
This operation is destructive and permanent. The message will be permanently removed from the mailbox and cannot be recovered. Consider moving the message to a Trash folder using imap_move_message instead if you want the ability to recover deleted messages.

​
Confirmation requirement

The confirm parameter must be set to the literal boolean value true. This explicit confirmation is required to prevent accidental deletions.
If confirm is not set to true, the request will be rejected with an invalid_input error.

​
Common use cases

  • Permanently remove spam or unwanted messages
  • Delete messages after processing or archiving elsewhere
  • Clean up test or temporary messages
  • Implement retention policies for old messages
  • Free up mailbox storage space
For safer deletion with recovery options, consider using imap_move_message to move messages to a Trash or Deleted Items folder instead of permanent deletion.

​
Input parameters

​
body.account_id
string
default:"default"
Account identifier. Must match pattern ^[A-Za-z0-9_-]{1,64}$.
​
body.message_id
string
required
Message identifier in format imap:{account_id}:{mailbox}:{uidvalidity}:{uid}.The account_id in the message_id must match the account_id parameter.
​
body.confirm
boolean
required
Must be set to the literal boolean value true to confirm the deletion.This is a safety mechanism to prevent accidental deletions.

​
Response

​
summary
string
Human-readable one-line outcome: "Message deleted"
​
data
object
​
meta
object

​
Example request

{
  "account_id": "default",
  "message_id": "imap:default:INBOX:1234567890:42",
  "confirm": true
}

​
Example response

{
  "summary": "Message deleted",
  "data": {
    "status": "ok",
    "issues": [],
    "account_id": "default",
    "mailbox": "INBOX",
    "message_id": "imap:default:INBOX:1234567890:42",
    "steps_attempted": 3,
    "steps_succeeded": 3
  },
  "meta": {
    "now_utc": "2026-03-03T22:30:15.123Z",
    "duration_ms": 456
  }
}

​
Error responses

{
  "error": {
    "code": "invalid_input",
    "message": "write tools are disabled; set MAIL_IMAP_WRITE_ENABLED=true",
    "details": {}
  },
  "meta": {
    "now_utc": "2026-03-03T22:30:15.123Z",
    "duration_ms": 5
  }
}

​
Implementation notes

​
Deletion process

The deletion operation consists of three steps:
  1. Connect and authenticate (steps_attempted=1)
    • Opens a connection to the IMAP server
    • Authenticates with the account credentials
    • Selects the mailbox in read-write mode
    • Verifies the message’s uidvalidity matches the current mailbox state
  2. Mark as deleted (steps_attempted=2)
    • Adds the \Deleted flag to the message using UID STORE +FLAGS.SILENT (\Deleted)
    • The message remains visible but is marked for deletion
  3. Expunge (steps_attempted=3)
    • Permanently removes the message using UID EXPUNGE
    • The message is immediately removed from the mailbox
    • The message cannot be recovered after this step

​
Partial deletion states

If steps_succeeded=2 but the expunge fails:
  • The message has the \Deleted flag set
  • The message is still visible in the mailbox (to IMAP clients that show deleted messages)
  • The next EXPUNGE operation (from any client) will permanently remove it
  • Some email clients hide messages with \Deleted flag automatically

​
Safety guarantees

  • Explicit confirmation required: The confirm parameter must be exactly true
  • Write gate check: MAIL_IMAP_WRITE_ENABLED=true must be set
  • UIDValidity verification: Ensures the message hasn’t changed since the message_id was obtained
  • Atomic flag+expunge: Uses UID EXPUNGE to expunge only the specific message, not all deleted messages

​
Recovery options

Once a message is expunged, it cannot be recovered through the IMAP protocol. Some email providers may offer server-side recovery options through their web interfaces, but this is not guaranteed.
Safer alternatives:
  • Use imap_move_message to move to a Trash folder
  • Implement a soft-delete workflow with custom flags
  • Archive messages to external storage before deletion

​
See also

Build docs developers (and LLMs) love

Get started for freeTalk to us