Modify messages

POST /api/v1/accounts/{accountId}/messages/actions

Apply one mailbox action to a batch of messages.

Authentication

Pass a Fluxmail API key as a bearer token. The key determines the member, mailbox scope, and permissions for the request.

Request

curl 'http://localhost:8977/api/v1/accounts/acct_123/messages/actions' \
  -X POST \
  -H "Authorization: Bearer $FLUXMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "messageIds": [
    "msg_123"
  ],
  "action": "markRead"
}'

Parameters

Name	Location	Required	Type	Details
`accountId`	path	Yes	`string`	Minimum length: 1.

Request body

Content type: application/json

{
  "type": "object",
  "properties": {
    "messageIds": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "example": "msg_123"
      },
      "minItems": 1
    },
    "action": {
      "type": "string",
      "enum": [
        "markRead",
        "markUnread",
        "star",
        "unstar",
        "archive",
        "trash",
        "untrash",
        "delete",
        "move",
        "addLabels",
        "removeLabels"
      ]
    },
    "folder": {
      "type": "string",
      "minLength": 1,
      "description": "Required when action is move. Use archive or trash instead of moving to those folders."
    },
    "labels": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1
      },
      "maxItems": 100,
      "description": "Required when action is addLabels or removeLabels. Change system labels with dedicated actions."
    }
  },
  "required": [
    "messageIds",
    "action"
  ],
  "additionalProperties": false
}

Responses

Status	Description	Content type
`200`	Messages modified	`application/json`
`400`	Invalid request	`application/json`
`401`	Authentication required	`application/json`
`403`	Permission or plan denied	`application/json`
`404`	Resource not found	`application/json`
`409`	Request conflict	`application/json`
`422`	Unsupported capability	`application/json`
`429`	Provider rate limit	`application/json`
`500`	Internal error	`application/json`
`503`	Provider unavailable	`application/json`

200 response

{
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "modified": {
          "type": "integer"
        },
        "action": {
          "type": "string",
          "enum": [
            "markRead",
            "markUnread",
            "star",
            "unstar",
            "archive",
            "trash",
            "untrash",
            "delete",
            "move",
            "addLabels",
            "removeLabels"
          ]
        }
      },
      "required": [
        "modified",
        "action"
      ],
      "additionalProperties": false
    },
    "warnings": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "data"
  ],
  "additionalProperties": false
}