Trash a message

POST

/v1/messages/{id}/trash

curl --request POST \
  --url https://api.inboxcnx.com/v1/messages/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/trash \
  --header 'Authorization: Bearer <token>'

Moves a message to the trash at the provider, to delete it the way the end user’s mail client would. The provider empties its trash on its own schedule (Gmail after 30 days). The stored copy stays, and untrash brings it back.

Requires the delete:messages scope.

Authorizations

• apiKey
• grantToken

Parameters

Path Parameters

id

required

string format: uuid

Responses

200

The message’s new state

Media typeapplication/json

object

id

required

string

keywords

required

object

key

additional properties

boolean

labels

required

object

system

required

Array<string>

Allowed values: inbox archive drafts sent trash junk all flagged important

custom

required

Array<string>

stateAt

required

string | null

Example

{
  "id": "c4a7e2b9-1d3f-4e6a-8b0c-5f2d9e7a1b34",
  "keywords": {
    "$seen": true
  },
  "labels": {
    "system": [
      "trash"
    ],
    "custom": []
  },
  "stateAt": "2026-10-23T08:00:00.000Z"
}

400

The id is not a UUID

Media typeapplication/json

object

error

required

object

code

required

string

message

required

string

Example ^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}

403

The credential lacks the delete:messages scope

Media typeapplication/json

object

error

required

object

code

required

string

message

required

string

Example ^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}

404

message_not_found: no such message. provider_message_not_found: the provider no longer has it

Media typeapplication/json

object

error

required

object

code

required

string

message

required

string

Example ^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}

409

message_deleted: the mail is deleted at the provider. connection_unreadable: the mailbox cannot be reached and may need a reconnect. connection_scope_missing: the end user did not grant the scope the action needs, named in scope. A reconnect grants it

Media typeapplication/json

object

error

required

object

code

required

string

message

required

string

Example ^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}

503

provider_unavailable: the provider is down or rate-limits the mailbox. Retry after Retry-After seconds

Media typeapplication/json

object

error

required

object

code

required

string

message

required

string

Example ^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}