post/users/@me/messages/bulk-delete-mine

Delete my messages with optional filters

Immediately deletes messages the caller has authored, subject to optional date-range and per-context filters (DMs, group DMs, guilds, with optional guild exclusions; or an inaccessible-only mode for contexts the caller is no longer a member of). Requires sudo mode verification. The deletion runs asynchronously; the caller receives a system DM with totals when it completes.

bulk_delete_my_messages

Request body

application/json

json

{
  "type": "object",
  "properties": {
    "scope": {
      "type": "string",
      "enum": [
        "selected",
        "inaccessible_only"
      ],
      "x-enumNames": [
        "Selected",
        "Inaccessible Only"
      ],
      "x-enumDescriptions": [
        "Delete messages matching the explicit include_* toggles and excluded_guild_ids.",
        "Delete only messages in places the caller no longer has access to (guilds left or removed from, group DMs left). Direct messages are not affected by this mode since the caller can always reopen them."
      ],
      "description": "Which set of contexts the deletion targets"
    },
    "include_dms": {
      "type": "boolean",
      "description": "Include 1:1 direct messages the caller still has open."
    },
    "include_dms_closed": {
      "type": "boolean",
      "description": "Include 1:1 direct messages the caller has previously closed. Independent of include_dms — set include_dms=false and include_dms_closed=true to target closed DMs only."
    },
    "include_group_dms": {
      "type": "boolean",
      "description": "Include group DMs the caller is still a member of."
    },
    "include_guilds": {
      "type": "boolean",
      "description": "Include text channels in guilds the caller is a member of."
    },
    "guild_filter_mode": {
      "type": "string",
      "enum": [
        "exclude",
        "include_only"
      ],
      "x-enumNames": [
        "Exclude",
        "Include Only"
      ],
      "x-enumDescriptions": [
        "Apply to every guild except those listed in excluded_guild_ids.",
        "Apply only to the guilds listed in included_guild_ids; all other guilds are left untouched."
      ],
      "description": "How the guild filter list is interpreted when include_guilds is true."
    },
    "excluded_guild_ids": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/SnowflakeType"
      },
      "maxItems": 500,
      "description": "Guild IDs to leave untouched. Used when include_guilds is true, guild_filter_mode is exclude, and scope is selected."
    },
    "included_guild_ids": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/SnowflakeType"
      },
      "maxItems": 500,
      "description": "The only guild IDs to apply this operation to. Used when include_guilds is true, guild_filter_mode is include_only, and scope is selected."
    },
    "start_date": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ],
      "description": "Inclusive ISO8601 lower bound for message timestamps. Null/omitted means unbounded in the past."
    },
    "end_date": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ],
      "description": "Exclusive ISO8601 upper bound for message timestamps. Null/omitted means unbounded in the future."
    },
    "password": {
      "$ref": "#/components/schemas/PasswordType"
    },
    "mfa_method": {
      "type": "string",
      "enum": [
        "totp",
        "webauthn"
      ],
      "x-enumNames": [
        "TOTP",
        "WebAuthn"
      ],
      "x-enumDescriptions": [
        "Time-based one-time password authentication via authenticator app",
        "Security key or biometric authentication"
      ],
      "description": "MFA method to use for verification"
    },
    "mfa_code": {
      "type": "string",
      "description": "MFA verification code from an authenticator app"
    },
    "webauthn_response": {
      "type": "object",
      "description": "WebAuthn authentication response"
    },
    "webauthn_challenge": {
      "type": "string",
      "description": "WebAuthn challenge string"
    }
  }
}

Responses

204

No Content

400

Bad Request - The request was malformed or contained invalid data

json

{
  "type": "object",
  "properties": {
    "code": {
      "$ref": "#/components/schemas/APIErrorCode"
    },
    "message": {
      "type": "string",
      "description": "Human-readable error message"
    },
    "errors": {
      "type": "array",
      "description": "Field-specific validation errors",
      "items": {
        "$ref": "#/components/schemas/ValidationErrorItem"
      }
    }
  },
  "required": [
    "code",
    "message"
  ]
}

401

Unauthorized - Authentication is required or the token is invalid

json

{
  "type": "object",
  "properties": {
    "code": {
      "$ref": "#/components/schemas/APIErrorCode"
    },
    "message": {
      "type": "string",
      "description": "Human-readable error message"
    },
    "errors": {
      "type": "array",
      "description": "Field-specific validation errors",
      "items": {
        "$ref": "#/components/schemas/ValidationErrorItem"
      }
    }
  },
  "required": [
    "code",
    "message"
  ]
}

403

Forbidden - You do not have permission to perform this action

json

{
  "type": "object",
  "properties": {
    "code": {
      "$ref": "#/components/schemas/APIErrorCode"
    },
    "message": {
      "type": "string",
      "description": "Human-readable error message"
    },
    "errors": {
      "type": "array",
      "description": "Field-specific validation errors",
      "items": {
        "$ref": "#/components/schemas/ValidationErrorItem"
      }
    }
  },
  "required": [
    "code",
    "message"
  ]
}

429

Too Many Requests - You are being rate limited

json

{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "enum": [
        "RATE_LIMITED"
      ]
    },
    "message": {
      "type": "string"
    },
    "retry_after": {
      "type": "number",
      "description": "Seconds to wait before retrying"
    },
    "global": {
      "type": "boolean",
      "description": "Whether this is a global rate limit"
    }
  },
  "required": [
    "code",
    "message",
    "retry_after"
  ]
}

500

Internal Server Error - An unexpected error occurred

json

{
  "type": "object",
  "properties": {
    "code": {
      "$ref": "#/components/schemas/APIErrorCode"
    },
    "message": {
      "type": "string",
      "description": "Human-readable error message"
    },
    "errors": {
      "type": "array",
      "description": "Field-specific validation errors",
      "items": {
        "$ref": "#/components/schemas/ValidationErrorItem"
      }
    }
  },
  "required": [
    "code",
    "message"
  ]
}