**API versions** · **V2 (Latest)** · [V1](/integrations/v1/docs?lang=en)

# Campaigns

OpenAPI 3.0.3 · API 2.0.0

```json
[
  {
    "url": "https://api.unisoft.world/integrations/v2",
    "description": "API"
  }
]
```

Message campaigns (WhatsApp / SMS / Email + fallback cascades). The draft (state INIT) is fully editable; SENDING is a SEPARATE, higher-risk action behind the `messages:send` scope (real mass send: SMS cost, WhatsApp ban risk, GDPR). Preview the audience with GET /{id}/targets before sending. Scopes: `messages:read` (also covers WhatsApp numbers & messaging configs) / `messages:write` (also covers uploads) / `messages:send`.

## Operations

## GET /campaigns

List campaigns

`list_campaigns`

Required scope: `messages:read`. Lists the org's campaigns with delivery stats. Paginated. Filter with `?state` (INIT|VALIDATE|FINISHED) or `?type`.

### Authentication

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Required permissions

```json
{
  "accepted": "messages:read",
  "additional": []
}
```

### Parameters

```json
{
  "name": "limit",
  "in": "query",
  "schema": {
    "type": "integer",
    "minimum": 1,
    "maximum": 200,
    "default": 50
  },
  "description": "Number of results per page"
}
```

```json
{
  "name": "cursor",
  "in": "query",
  "schema": {
    "type": "string"
  },
  "description": "Opaque cursor returned by the previous request"
}
```

```json
{
  "name": "state",
  "in": "query",
  "schema": {
    "type": "string",
    "enum": [
      "INIT",
      "VALIDATE",
      "FINISHED"
    ]
  }
}
```

```json
{
  "name": "type",
  "in": "query",
  "schema": {
    "type": "string"
  }
}
```

### Responses

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Campaign"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/Pagination"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "ERROR",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "ERROR"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "INSUFFICIENT_SCOPE"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "messages:read",
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /campaigns

Create a campaign (draft)

`create_campaign`

Required scope: `messages:write`. Creates a campaign in state INIT (draft). Does NOT send — use POST /{id}/send. Targeting is mutually exclusive (allContact | staredOnly | categories).

### Authentication

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Required permissions

```json
{
  "accepted": "messages:write",
  "additional": []
}
```

### Request body

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/UnisoftRequest_a64ca28f296f1c41c444"
      }
    }
  }
}
```

### Responses

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "$ref": "#/components/schemas/Campaign"
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "VALIDATION_ERROR",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "VALIDATION_ERROR"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "INSUFFICIENT_SCOPE"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "messages:write",
  "x-unisoft-mcp": {
    "category": "create",
    "readOnly": false,
    "destructive": false,
    "idempotent": false,
    "warn": false
  }
}
```

## GET /campaigns/sms/available

Remaining SMS quota

`get_sms_quota`

Required scope: `messages:read`. Returns the org's remaining SMS credits (useful before sending an SMS campaign).

### Authentication

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Required permissions

```json
{
  "accepted": "messages:read",
  "additional": []
}
```

### Responses

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "total": {
                "type": "integer"
              }
            }
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "messages:read",
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /campaigns/{id}

Get a campaign

`get_campaign`

Required scope: `messages:read`. Full campaign incl. delivery stats.

### Authentication

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Required permissions

```json
{
  "accepted": "messages:read",
  "additional": []
}
```

### Parameters

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
    "format": "uuid"
  },
  "description": "Identifier of the existing target resource, returned by its authorised list or read operation. Never generate a new UUID to address an existing record."
}
```

### Responses

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "$ref": "#/components/schemas/Campaign"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "messages:read",
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## PATCH /campaigns/{id}

Update a draft campaign

`update_campaign`

Required scope: `messages:write`. Update only an admitted INIT draft. A durable private command journal and shared campaign fence precede changes; the response includes commandId. Read get_campaign_update_receipt with the same campaign, command and API principal after a missing or uncertain response. COMPLETED with queueAdmission=NOT_STARTED acknowledges only the draft edit; it does not send. There is no caller idempotency key on this legacy PATCH, so never repeat it to bypass an unresolved command. A current INIT state alone does not prove that an earlier command had no effect. A proven edit survives an accessory statistics-read failure. Pending or uncertain effects retain the fence. The external fence does not serialize internal editors. For saved CRM audience review and dispatch, use preview_saved_campaign_dispatch and dispatch_saved_campaign_audience.

### Authentication

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Required permissions

```json
{
  "accepted": "messages:write",
  "additional": []
}
```

### Parameters

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
    "format": "uuid"
  },
  "description": "Identifier of the existing target resource, returned by its authorised list or read operation. Never generate a new UUID to address an existing record."
}
```

### Request body

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/UnisoftRequest_eb7a1a258ea96fc9aa42"
      }
    }
  }
}
```

### Responses

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "$ref": "#/components/schemas/Campaign"
          },
          "commandId": {
            "type": "string",
            "format": "uuid"
          }
        },
        "required": [
          "commandId"
        ]
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "VALIDATION_ERROR",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "VALIDATION_ERROR"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "NOT_FOUND"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "CAMPAIGN_NOT_EDITABLE",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "CAMPAIGN_NOT_EDITABLE"
          }
        }
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "Uncertain legacy mutation. Preserve commandId and inspect its dedicated receipt without repeating the effect.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "pattern": "^[A-Z][A-Z0-9_]{0,127}$"
          },
          "commandId": {
            "type": "string",
            "format": "uuid"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "messages:write",
  "x-unisoft-mcp": {
    "category": "update",
    "readOnly": false,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## DELETE /campaigns/{id}

Delete a campaign

`delete_campaign`

Required scope: `messages:write`. Soft-deletes the campaign.

### Authentication

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Required permissions

```json
{
  "accepted": "messages:write",
  "additional": []
}
```

### Parameters

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
    "format": "uuid"
  },
  "description": "Identifier of the existing target resource, returned by its authorised list or read operation. Never generate a new UUID to address an existing record."
}
```

### Responses

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "messages:write",
  "x-unisoft-mcp": {
    "category": "delete",
    "readOnly": false,
    "destructive": true,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /campaigns/{id}/duplicate

Duplicate a campaign

`duplicate_campaign`

Required scope: `messages:write`. Duplicates the campaign as a fresh INIT draft (new id, scheduledAt cleared, stats reset; media shared by reference).

### Authentication

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Required permissions

```json
{
  "accepted": "messages:write",
  "additional": []
}
```

### Parameters

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
    "format": "uuid"
  },
  "description": "Identifier of the existing target resource, returned by its authorised list or read operation. Never generate a new UUID to address an existing record."
}
```

### Responses

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "$ref": "#/components/schemas/Campaign"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "messages:write",
  "x-unisoft-mcp": {
    "category": "create",
    "readOnly": false,
    "destructive": false,
    "idempotent": false,
    "warn": false
  }
}
```

## GET /campaigns/{id}/targets

Preview the recipient count

`preview_campaign_targets`

Required scope: `messages:read`. Counts the recipients the campaign's stored targeting resolves to, WITHOUT creating any delivery. Returns 0 if no targeting is set.

### Authentication

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Required permissions

```json
{
  "accepted": "messages:read",
  "additional": []
}
```

### Parameters

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
    "format": "uuid"
  },
  "description": "Identifier of the existing target resource, returned by its authorised list or read operation. Never generate a new UUID to address an existing record."
}
```

### Responses

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "$ref": "#/components/schemas/CampaignTargets"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "messages:read",
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /campaigns/{id}/send

Send the campaign (real mass send)

`send_campaign`

Required scope: `messages:send`. Real mass sending requires the user's explicit request for this campaign and audience. For legacy stored targeting, preview_campaign_targets is passive; saved CRM targeting instead uses preview_saved_campaign_dispatch and dispatch_saved_campaign_audience. Stored targeting, delivery references and hosted media are admitted before a durable private journal and the shared campaign fence. Native INIT-to-VALIDATE transition and positively acknowledged initial queue admission produce commandId, state and targets; neither queued nor finished proves recipient delivery. This can incur channel costs. Missing targeting returns CAMPAIGN_TARGETING_REQUIRED; invalid references, changed snapshots and existing send states are refused. There is no caller idempotency key on this legacy POST. After an uncertain or missing response, read get_campaign_send_receipt using the same campaign, command and principal; never send again, change UUID, duplicate the campaign or infer non-execution from INIT. DISPATCH_RESULT_UNKNOWN retains uncertainty and protections. An observed complete queue alone does not repair an unknown journal or acknowledgement. The external fence does not serialize internal senders. When the active SMS platform handles a primary or fallback SMS, this ordinary-audience command also requires messages:read, contacts:read and smsEstimateHash from preview_campaign_sms_usage. Ask the user to confirm the estimated maximum Unisoft units and the external-funded record count. Imported or annual-event SMS audiences require review in Unisoft.

### Authentication

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Required permissions

```json
{
  "accepted": "messages:send",
  "additional": []
}
```

### Parameters

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
    "format": "uuid"
  },
  "description": "Identifier of the existing target resource, returned by its authorised list or read operation. Never generate a new UUID to address an existing record."
}
```

### Request body

```json
{
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "smsEstimateHash": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$",
            "description": "Exact sms.estimateHash from preview_campaign_sms_usage when the SMS platform is active."
          }
        },
        "additionalProperties": false
      }
    }
  }
}
```

### Responses

#### HTTP 200

```json
{
  "description": "Acknowledged initial native queue admission; not recipient delivery.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "commandId",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "commandId": {
            "type": "string",
            "format": "uuid"
          },
          "data": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "state",
              "targets"
            ],
            "properties": {
              "state": {
                "type": "string",
                "enum": [
                  "VALIDATE"
                ]
              },
              "targets": {
                "type": "integer",
                "minimum": 0,
                "maximum": 2000
              }
            }
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "NOT_FOUND"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "CAMPAIGN_ALREADY_SENT",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "CAMPAIGN_ALREADY_SENT"
          }
        }
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "Uncertain legacy mutation. Preserve commandId and inspect its dedicated receipt without repeating the effect.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string",
            "pattern": "^[A-Z][A-Z0-9_]{0,127}$"
          },
          "commandId": {
            "type": "string",
            "format": "uuid"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-conditional-scopes": [
    {
      "condition": "The active SMS platform handles this campaign’s primary or fallback SMS channel.",
      "scopes": [
        "messages:read",
        "contacts:read"
      ],
      "allRequired": true
    }
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-scope": "messages:send",
  "x-unisoft-mcp": {
    "category": "action",
    "readOnly": false,
    "destructive": true,
    "idempotent": false,
    "warn": true
  }
}
```

## POST /campaigns/{id}/test

Send a test to one contact (draft only)

`test_campaign`

Required scope: `messages:send`. Sends a single test message of the campaign to one contact (real send to that contact; excluded from stats; ignores the unsubscribe list). Allowed ONLY while the campaign is a draft (state INIT) — returns 409 otherwise. Body: {contactId}.

### Authentication

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Required permissions

```json
{
  "accepted": "messages:send",
  "additional": []
}
```

### Parameters

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
    "format": "uuid"
  },
  "description": "Identifier of the existing target resource, returned by its authorised list or read operation. Never generate a new UUID to address an existing record."
}
```

### Request body

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "contactId": {
            "type": "string",
            "description": "Contact to send the test to."
          }
        },
        "required": [
          "contactId"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### Responses

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "VALIDATION_ERROR",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "VALIDATION_ERROR"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "NOT_FOUND"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "CAMPAIGN_NOT_DRAFT",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "CAMPAIGN_NOT_DRAFT"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "messages:send",
  "x-unisoft-mcp": {
    "category": "action",
    "readOnly": false,
    "destructive": true,
    "idempotent": false,
    "warn": true
  }
}
```

## GET /campaigns/sms/wallet

Read the Unisoft SMS unit balance

`get_sms_wallet`

Requires messages:read. Reports whether the SMS platform is enabled and whether the organisation’s wallet has migrated. A migrated wallet reports committed available, reserved, consumed and granted Unisoft units. External credits are separate. Campaign-restricted keys cannot use this operation.

### Authentication

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Required permissions

```json
{
  "accepted": "messages:read",
  "additional": []
}
```

### Responses

#### HTTP 200

```json
{
  "description": "Read-only SMS observation.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "type": "object",
            "properties": {
              "enabled": {
                "type": "boolean"
              },
              "wallet": {
                "type": "object",
                "properties": {
                  "migrated": {
                    "type": "boolean"
                  },
                  "available": {
                    "type": "integer",
                    "minimum": -9007199254740991,
                    "maximum": 9007199254740991
                  },
                  "reserved": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 9007199254740991
                  },
                  "consumed": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 9007199254740991
                  },
                  "granted": {
                    "type": "integer",
                    "minimum": -9007199254740991,
                    "maximum": 9007199254740991
                  },
                  "revision": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 9007199254740991
                  }
                },
                "required": [
                  "migrated"
                ],
                "additionalProperties": false
              }
            },
            "required": [
              "enabled",
              "wallet"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "success",
          "data"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid filter or request.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Missing scope or restricted organisation access.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "messages:read",
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  },
  "x-unisoft-mcp-output-schema": true
}
```

## GET /campaigns/sms/journal

Read SMS dispatch and unit consumption history

`get_sms_journal`

Requires messages:read and contacts:read in the same organisation and whole-organisation contact access. Lists new-platform SMS dispatch records with their funding, segments, unit consumption and delivery evidence. Each page has up to 25 rows. A provider acceptance is distinct from delivery. An uncertain outcome is never automatically retried. The response omits phone numbers, message content, provider identifiers and purchase costs. Date-only bounds are inclusive in UTC; an exact UTC to instant is exclusive.

### Authentication

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Required permissions

```json
{
  "accepted": "messages:read",
  "additional": [
    "contacts:read"
  ]
}
```

### Parameters

```json
{
  "name": "page",
  "in": "query",
  "schema": {
    "type": "integer",
    "minimum": 1,
    "maximum": 100000
  }
}
```

```json
{
  "name": "funding",
  "in": "query",
  "schema": {
    "type": "string",
    "enum": [
      "unisoft",
      "external"
    ]
  }
}
```

```json
{
  "name": "state",
  "in": "query",
  "schema": {
    "type": "string",
    "enum": [
      "PREPARED",
      "SENDING",
      "ACCEPTED",
      "REJECTED",
      "BLOCKED",
      "UNCERTAIN",
      "CANCELED",
      "SIMULATED"
    ]
  }
}
```

```json
{
  "name": "number",
  "in": "query",
  "schema": {
    "type": "string",
    "pattern": "^\\+[1-9][0-9]{1,14}$"
  }
}
```

```json
{
  "name": "campaign",
  "in": "query",
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

```json
{
  "name": "contact",
  "in": "query",
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

```json
{
  "name": "country",
  "in": "query",
  "schema": {
    "type": "string",
    "pattern": "^[A-Z]{2}$"
  }
}
```

```json
{
  "name": "source",
  "in": "query",
  "schema": {
    "type": "string",
    "enum": [
      "campaign",
      "reminder",
      "pledge",
      "automatic"
    ]
  }
}
```

```json
{
  "name": "from",
  "in": "query",
  "schema": {
    "type": "string"
  }
}
```

```json
{
  "name": "to",
  "in": "query",
  "schema": {
    "type": "string"
  }
}
```

### Responses

#### HTTP 200

```json
{
  "description": "Read-only SMS observation.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "type": "object",
            "properties": {
              "total": {
                "type": "integer",
                "minimum": 0,
                "maximum": 9007199254740991
              },
              "page": {
                "type": "integer",
                "minimum": 1,
                "maximum": 9007199254740991
              },
              "pageSize": {
                "type": "integer",
                "enum": [
                  25
                ]
              },
              "unitsConsumed": {
                "type": "integer",
                "minimum": 0,
                "maximum": 9007199254740991
              },
              "entries": {
                "type": "array",
                "maxItems": 25,
                "items": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "country": {
                      "type": "string",
                      "nullable": true
                    },
                    "source": {
                      "type": "string",
                      "enum": [
                        "campaign",
                        "reminder",
                        "pledge",
                        "automatic"
                      ]
                    },
                    "campaign": {
                      "type": "string",
                      "nullable": true
                    },
                    "test": {
                      "type": "boolean"
                    },
                    "provider": {
                      "type": "string",
                      "nullable": true,
                      "description": "Unisoft-funded dispatches report unisoft. External dispatches report the connected provider."
                    },
                    "funding": {
                      "type": "string",
                      "enum": [
                        "unisoft",
                        "external"
                      ],
                      "nullable": true
                    },
                    "state": {
                      "type": "string",
                      "enum": [
                        "PREPARED",
                        "SENDING",
                        "ACCEPTED",
                        "REJECTED",
                        "BLOCKED",
                        "UNCERTAIN",
                        "CANCELED",
                        "SIMULATED"
                      ]
                    },
                    "code": {
                      "type": "string",
                      "nullable": true
                    },
                    "encoding": {
                      "type": "string",
                      "nullable": true
                    },
                    "segments": {
                      "type": "integer",
                      "minimum": 0,
                      "maximum": 9007199254740991,
                      "nullable": true
                    },
                    "coefficient": {
                      "type": "integer",
                      "minimum": 0,
                      "maximum": 9007199254740991,
                      "nullable": true
                    },
                    "unitsEstimated": {
                      "type": "integer",
                      "minimum": 0,
                      "maximum": 9007199254740991,
                      "nullable": true
                    },
                    "unitsConsumed": {
                      "type": "integer",
                      "minimum": 0,
                      "maximum": 9007199254740991
                    },
                    "simulated": {
                      "type": "boolean",
                      "nullable": true
                    },
                    "delivery": {
                      "type": "string",
                      "nullable": true
                    },
                    "deliveryAt": {
                      "type": "string",
                      "format": "date-time",
                      "nullable": true
                    }
                  },
                  "required": [
                    "id",
                    "at",
                    "source",
                    "test",
                    "state",
                    "unitsConsumed",
                    "delivery",
                    "deliveryAt"
                  ],
                  "additionalProperties": false
                }
              }
            },
            "required": [
              "total",
              "page",
              "pageSize",
              "unitsConsumed",
              "entries"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "success",
          "data"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid filter or request.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object"
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Missing scope or restricted organisation access.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object"
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "messages:read",
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  },
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-additional-scopes": [
    "contacts:read"
  ]
}
```

## POST /campaigns/{id}/rescheduling-preview

Preview moving an untouched future campaign queue

`preview_campaign_rescheduling`

Requires explicit messages:reschedule AND messages:read AND messages:send. Campaign-restricted keys are refused. This moves the existing materialized native queue of a VALIDATE campaign; it never resolves, refreshes, adds or removes audience members, content, channels, prices or provider settings. Use the campaign UUID, not a delivery/contact/command id. First preview_campaign_rescheduling with scheduledAt as a strict RFC3339 instant with timezone, then request_campaign_rescheduling with exactly that canonical scheduledAt, expectedRevision, one stable idempotencyKey UUID and acknowledgeQueue:true. The campaign must have a valid native dispatchToken, a positive targets count matching every non-test queued delivery, and a stored BSON future schedule; each EMAIL/SMS/WHATSAPP target must remain INIT, share that schedule, have an exact scalar globally unique delivery identity and have no attempt/progress/provider/claim/error/cancellation marker. Tests are excluded and never moved. Missing queue-completeness proof, app-mobile delivery, any started/due/ambiguous target or concurrent change refuses the whole plan. Both old and new dates must remain over 60 seconds in the future; the adapter bounds its write phase to 10 seconds. This safety window is not a delivery-time guarantee. At most 2000 non-test targets and 2100 total group/source reference rows (including tests), within an 8 MiB source snapshot, are admitted. Preview hashes the exact current campaign and recipient queue plus proposed instant, returning counts/channels only, never recipients, private content or provider secrets. The command journals durably and acquires the shared campaign-operation fence before exact per-document BSON CAS updates of send.scheduledAt and the campaign schedule. It does not call a sender, daemon or provider. Native workers later retain their own eligibility and delivery rules. The fence has no expiring lease that can replay effects; emergency STOP can request preemption, and every next external write checks it. Internal writers/workers are not transactionally locked. A crash, partial write, unknown ACK, lost response or UNKNOWN state retains protection and never permits automatic retry, another key or a standard-send bypass. Read get_campaign_rescheduling_command using the original commandId, principal and organisation. SCHEDULED proves the exact future dates were recorded, not that sending, delivery or synchronization occurred. PENDING/RUNNING can be interrupted and changedDeliveryCount stays null unless SCHEDULED. fenceReleased:false can accompany a proven SCHEDULED result when housekeeping remains unresolved; it does not undo that schedule or authorize another action. A successful finalization is never downgraded because fence housekeeping failed. No future audience refresh is implied. Only declared inputs, no query parameters or GET body.

### Authentication

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Required permissions

```json
{
  "accepted": "messages:reschedule",
  "additional": [
    "messages:read",
    "messages:send"
  ]
}
```

### Parameters

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### Request body

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "scheduledAt": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "scheduledAt"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### Responses

#### HTTP 200

```json
{
  "description": "Exact scheduling plan or durable command state.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/CampaignReschedulingPreview"
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid UUID, strict timestamp or closed input."
}
```

#### HTTP 401

```json
{
  "description": "Authentication required."
}
```

#### HTTP 403

```json
{
  "description": "Current grants missing or campaign-restricted principal."
}
```

#### HTTP 404

```json
{
  "description": "Current campaign or command unavailable."
}
```

#### HTTP 409

```json
{
  "description": "Stale preview, started/ambiguous queue, missing completeness, stop or operation fence. No bypass or audience refresh."
}
```

#### HTTP 500

```json
{
  "description": "Unknown scheduling outcome; read original command without replay."
}
```

#### HTTP 503

```json
{
  "description": "Journal/fence acknowledgement unavailable; preserve original command identity."
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "messages:reschedule",
  "x-unisoft-additional-scopes": [
    "messages:read",
    "messages:send"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /campaigns/{id}/rescheduling-commands

Move an untouched future campaign queue

`request_campaign_rescheduling`

Requires explicit messages:reschedule AND messages:read AND messages:send. Campaign-restricted keys are refused. This moves the existing materialized native queue of a VALIDATE campaign; it never resolves, refreshes, adds or removes audience members, content, channels, prices or provider settings. Use the campaign UUID, not a delivery/contact/command id. First preview_campaign_rescheduling with scheduledAt as a strict RFC3339 instant with timezone, then request_campaign_rescheduling with exactly that canonical scheduledAt, expectedRevision, one stable idempotencyKey UUID and acknowledgeQueue:true. The campaign must have a valid native dispatchToken, a positive targets count matching every non-test queued delivery, and a stored BSON future schedule; each EMAIL/SMS/WHATSAPP target must remain INIT, share that schedule, have an exact scalar globally unique delivery identity and have no attempt/progress/provider/claim/error/cancellation marker. Tests are excluded and never moved. Missing queue-completeness proof, app-mobile delivery, any started/due/ambiguous target or concurrent change refuses the whole plan. Both old and new dates must remain over 60 seconds in the future; the adapter bounds its write phase to 10 seconds. This safety window is not a delivery-time guarantee. At most 2000 non-test targets and 2100 total group/source reference rows (including tests), within an 8 MiB source snapshot, are admitted. Preview hashes the exact current campaign and recipient queue plus proposed instant, returning counts/channels only, never recipients, private content or provider secrets. The command journals durably and acquires the shared campaign-operation fence before exact per-document BSON CAS updates of send.scheduledAt and the campaign schedule. It does not call a sender, daemon or provider. Native workers later retain their own eligibility and delivery rules. The fence has no expiring lease that can replay effects; emergency STOP can request preemption, and every next external write checks it. Internal writers/workers are not transactionally locked. A crash, partial write, unknown ACK, lost response or UNKNOWN state retains protection and never permits automatic retry, another key or a standard-send bypass. Read get_campaign_rescheduling_command using the original commandId, principal and organisation. SCHEDULED proves the exact future dates were recorded, not that sending, delivery or synchronization occurred. PENDING/RUNNING can be interrupted and changedDeliveryCount stays null unless SCHEDULED. fenceReleased:false can accompany a proven SCHEDULED result when housekeeping remains unresolved; it does not undo that schedule or authorize another action. A successful finalization is never downgraded because fence housekeeping failed. No future audience refresh is implied. Only declared inputs, no query parameters or GET body.

### Authentication

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Required permissions

```json
{
  "accepted": "messages:reschedule",
  "additional": [
    "messages:read",
    "messages:send"
  ]
}
```

### Parameters

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### Request body

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "scheduledAt": {
            "type": "string",
            "format": "date-time"
          },
          "idempotencyKey": {
            "type": "string",
            "format": "uuid"
          },
          "expectedRevision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "acknowledgeQueue": {
            "type": "boolean",
            "enum": [
              true
            ]
          }
        },
        "required": [
          "scheduledAt",
          "idempotencyKey",
          "expectedRevision",
          "acknowledgeQueue"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### Responses

#### HTTP 200

```json
{
  "description": "Exact scheduling plan or durable command state.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/CampaignReschedulingCommand"
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid UUID, strict timestamp or closed input."
}
```

#### HTTP 401

```json
{
  "description": "Authentication required."
}
```

#### HTTP 403

```json
{
  "description": "Current grants missing or campaign-restricted principal."
}
```

#### HTTP 404

```json
{
  "description": "Current campaign or command unavailable."
}
```

#### HTTP 409

```json
{
  "description": "Stale preview, started/ambiguous queue, missing completeness, stop or operation fence. No bypass or audience refresh."
}
```

#### HTTP 500

```json
{
  "description": "Unknown scheduling outcome; read original command without replay."
}
```

#### HTTP 503

```json
{
  "description": "Journal/fence acknowledgement unavailable; preserve original command identity."
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "messages:reschedule",
  "x-unisoft-additional-scopes": [
    "messages:read",
    "messages:send"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "action",
    "readOnly": false,
    "destructive": false,
    "idempotent": true,
    "warn": true
  }
}
```

## GET /campaigns/{id}/rescheduling-commands/{commandId}

Read campaign rescheduling without replay

`get_campaign_rescheduling_command`

Requires explicit messages:reschedule AND messages:read AND messages:send. Campaign-restricted keys are refused. This moves the existing materialized native queue of a VALIDATE campaign; it never resolves, refreshes, adds or removes audience members, content, channels, prices or provider settings. Use the campaign UUID, not a delivery/contact/command id. First preview_campaign_rescheduling with scheduledAt as a strict RFC3339 instant with timezone, then request_campaign_rescheduling with exactly that canonical scheduledAt, expectedRevision, one stable idempotencyKey UUID and acknowledgeQueue:true. The campaign must have a valid native dispatchToken, a positive targets count matching every non-test queued delivery, and a stored BSON future schedule; each EMAIL/SMS/WHATSAPP target must remain INIT, share that schedule, have an exact scalar globally unique delivery identity and have no attempt/progress/provider/claim/error/cancellation marker. Tests are excluded and never moved. Missing queue-completeness proof, app-mobile delivery, any started/due/ambiguous target or concurrent change refuses the whole plan. Both old and new dates must remain over 60 seconds in the future; the adapter bounds its write phase to 10 seconds. This safety window is not a delivery-time guarantee. At most 2000 non-test targets and 2100 total group/source reference rows (including tests), within an 8 MiB source snapshot, are admitted. Preview hashes the exact current campaign and recipient queue plus proposed instant, returning counts/channels only, never recipients, private content or provider secrets. The command journals durably and acquires the shared campaign-operation fence before exact per-document BSON CAS updates of send.scheduledAt and the campaign schedule. It does not call a sender, daemon or provider. Native workers later retain their own eligibility and delivery rules. The fence has no expiring lease that can replay effects; emergency STOP can request preemption, and every next external write checks it. Internal writers/workers are not transactionally locked. A crash, partial write, unknown ACK, lost response or UNKNOWN state retains protection and never permits automatic retry, another key or a standard-send bypass. Read get_campaign_rescheduling_command using the original commandId, principal and organisation. SCHEDULED proves the exact future dates were recorded, not that sending, delivery or synchronization occurred. PENDING/RUNNING can be interrupted and changedDeliveryCount stays null unless SCHEDULED. fenceReleased:false can accompany a proven SCHEDULED result when housekeeping remains unresolved; it does not undo that schedule or authorize another action. A successful finalization is never downgraded because fence housekeeping failed. No future audience refresh is implied. Only declared inputs, no query parameters or GET body.

### Authentication

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Required permissions

```json
{
  "accepted": "messages:reschedule",
  "additional": [
    "messages:read",
    "messages:send"
  ]
}
```

### Parameters

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

```json
{
  "name": "commandId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### Responses

#### HTTP 200

```json
{
  "description": "Exact scheduling plan or durable command state.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/CampaignReschedulingCommand"
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid UUID, strict timestamp or closed input."
}
```

#### HTTP 401

```json
{
  "description": "Authentication required."
}
```

#### HTTP 403

```json
{
  "description": "Current grants missing or campaign-restricted principal."
}
```

#### HTTP 404

```json
{
  "description": "Current campaign or command unavailable."
}
```

#### HTTP 409

```json
{
  "description": "Stale preview, started/ambiguous queue, missing completeness, stop or operation fence. No bypass or audience refresh."
}
```

#### HTTP 500

```json
{
  "description": "Unknown scheduling outcome; read original command without replay."
}
```

#### HTTP 503

```json
{
  "description": "Journal/fence acknowledgement unavailable; preserve original command identity."
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "messages:reschedule",
  "x-unisoft-additional-scopes": [
    "messages:read",
    "messages:send"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /campaigns/{id}/audience-dispatch-preview

Review real dispatch of a saved CRM campaign audience

`preview_saved_campaign_dispatch`

Requires messages:read and contacts:read, plus every native CRM source scope implied by saved listIds/excludedListIds and email_templates:read when a saved emailTemplate is used. Campaign-restricted keys are refused. Reads re-admit the persisted current API/OAuth key, open organisation, exact campaign, current CRM contacts/parents, list generations and source references, previous-campaign exclusions, sender references and existing hosted media. Only a saved crmTarget with a matching crmAudienceHash on an unchanged INIT draft is admitted. No categories/all-contact/import/form/annual-event fallback or inline audience override is used. Native exclusions rely on recorded SUCCESS non-test rows, not proof of inbox arrival or reading. A prior non-test delivery for this campaign blocks another dispatch. Missing/ambiguous/scalar-array data fails closed. Preview does not reserve a source or a provider, check live sender readiness, fetch media URLs or write a queue. Native SMS selection remains the organisation single-config owner; smsConfig is not a monetary reservation or provider selection. Initial queue admission is bounded to 2000 records and 16777216 bytes, including rendered content. Read this preview after composing and saving the audience. expectedRevision covers the reviewed content, current rendering and source/sender references; audienceHash must still match the saved native audience. preparedRecordCount counts initial queue rows, not future fallback attempts. selectedContactCount is the native selected source-contact count before recipient substitution, exclusions and reachability. An existing BSON scheduledAt is copied to each native row; no new schedule is accepted here. Use these exact values only for an explicitly authorised real mass send. No query parameters or request body are accepted. When sms is present, its estimateHash is the approval token for the maximum Unisoft SMS units, including possible fallbacks. External funding consumes no Unisoft units. Check unavailableRecords before asking the user to approve the units.

### Authentication

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Required permissions

```json
{
  "accepted": "messages:read",
  "additional": [
    "contacts:read"
  ]
}
```

### Parameters

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### Responses

#### HTTP 200

```json
{
  "description": "Current reviewed native dispatch plan; no journal, reservation, queue or provider effect.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/CampaignAudienceDispatchPreviewResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_UUID, INVALID_AUDIENCE_DISPATCH_INPUT or UNKNOWN_QUERY_PARAMETER: use only declared fields and the exact reviewed values.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "The API key or OAuth token is missing or invalid.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, CAMPAIGN_RESTRICTED_KEY or INVALID_ORGANISATION_CONTEXT: all required current capabilities and an open exact organisation are mandatory.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CAMPAIGN_NOT_FOUND or DISPATCH_COMMAND_NOT_FOUND: the exact campaign or same-principal command is unavailable.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "CAMPAIGN_CHANGED, SAVED_AUDIENCE_CHANGED, DISPATCH_AUDIENCE_EMPTY, CAMPAIGN_NOT_EDITABLE, CAMPAIGN_ALREADY_HAS_DELIVERIES or source/sender/media/fence conflicts. Read the command and current preview; never bypass an uncertain result with another key.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "DISPATCH_LIMIT_REACHED: at most 2000 initial rows and 16777216 queue bytes; narrow and save the audience before reviewing again.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "CAMPAIGN_DISPATCH_UNAVAILABLE: the outcome may be unknown; read the same command instead of sending again.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "DISPATCH_JOURNAL_UNCERTAIN, DISPATCH_SOURCE_UNAVAILABLE or CAMPAIGN_FENCE_UNCERTAIN: observe the same command; a missing response or ACK never authorizes replay.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "messages:read",
  "x-unisoft-additional-scopes": [
    "contacts:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  },
  "x-unisoft-conditional-scopes": [
    {
      "condition": "saved target list kind form",
      "scopes": [
        "forms:read",
        "forms_submit:read"
      ],
      "allRequired": true
    },
    {
      "condition": "saved target list kind product",
      "scopes": [
        "forms:read",
        "forms_submit:read"
      ],
      "allRequired": true
    },
    {
      "condition": "saved target list kind cagnotte",
      "scopes": [
        "caisses:read",
        "paiements:read"
      ],
      "allRequired": true
    },
    {
      "condition": "saved target list kind event",
      "scopes": [
        "events:read",
        "forms:read",
        "forms_submit:read",
        "caisses:read",
        "paiements:read"
      ],
      "allRequired": true
    },
    {
      "condition": "saved target list kind fundraising",
      "scopes": [
        "fundraising:read",
        "paiements:read",
        "abonnements:read",
        "promesses:read"
      ],
      "allRequired": true
    },
    {
      "condition": "saved emailTemplate is present",
      "scopes": [
        "email_templates:read"
      ],
      "allRequired": true
    }
  ]
}
```

## POST /campaigns/{id}/audience-dispatches

Queue an authorised saved CRM campaign audience

`dispatch_saved_campaign_audience`

Requires messages:read and contacts:read, plus every native CRM source scope implied by saved listIds/excludedListIds and email_templates:read when a saved emailTemplate is used. Campaign-restricted keys are refused. Reads re-admit the persisted current API/OAuth key, open organisation, exact campaign, current CRM contacts/parents, list generations and source references, previous-campaign exclusions, sender references and existing hosted media. Only a saved crmTarget with a matching crmAudienceHash on an unchanged INIT draft is admitted. No categories/all-contact/import/form/annual-event fallback or inline audience override is used. Native exclusions rely on recorded SUCCESS non-test rows, not proof of inbox arrival or reading. A prior non-test delivery for this campaign blocks another dispatch. Missing/ambiguous/scalar-array data fails closed. Preview does not reserve a source or a provider, check live sender readiness, fetch media URLs or write a queue. Native SMS selection remains the organisation single-config owner; smsConfig is not a monetary reservation or provider selection. Initial queue admission is bounded to 2000 records and 16777216 bytes, including rendered content. Requires the separate messages:send opt-in and an explicit user-authorised mass send. First call preview_saved_campaign_dispatch. Pass its exact expectedRevision, audienceHash and preparedRecordCount as expectedRecordCount, a stable UUID idempotencyKey and acknowledgeMassSend:true. A durable journal and common campaign mutation fence precede the last native preflight and INIT→VALIDATE reservation with targets/dispatchToken. The exact native recipient IDs and rendered payload are frozen before one bounded insertMany. Queue UUIDs are preserved so native unsubscribe links reference the actual rows. Every ACK, inserted ID and count must agree. QUEUED/queueAdmission=CONFIRMED is initial queue admission only; it is not SMTP delivery or reading. PENDING/UNCERTAIN or partial/unavailable observations never authorize replay, a new key, duplication or a test. The same principal/key/input only observes its prior result; changed intent conflicts. Unknown effects retain the fence without timeout stealing. STOP is preemptive and pending rows are canceled when its marker/latch is observed, but provider calls already handed off cannot be recalled. Another internal writer or worker can change after point-in-time checks; no global transaction or source reservation is promised. Known queue admission remains CONFIRMED if a terminal journal annotation or stop/fence cleanup is uncertain; inspect journalState, reservationStatus and stopCleanup separately. No provider is called inline. When the preview includes sms, show the maximum Unisoft units and external-funded record count to the user. Include the exact sms.estimateHash as smsEstimateHash. A changed quote, unapproved tariff or insufficient wallet blocks this command before queue admission. The per-message quote is frozen with the queued record and remains checked when the SMS worker reaches it.

### Authentication

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Required permissions

```json
{
  "accepted": "messages:send",
  "additional": [
    "messages:read",
    "contacts:read"
  ]
}
```

### Parameters

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### Request body

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "idempotencyKey": {
            "type": "string",
            "format": "uuid"
          },
          "expectedRevision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "audienceHash": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "expectedRecordCount": {
            "type": "integer",
            "minimum": 1,
            "maximum": 2000
          },
          "acknowledgeMassSend": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "smsEstimateHash": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          }
        },
        "required": [
          "idempotencyKey",
          "expectedRevision",
          "audienceHash",
          "expectedRecordCount",
          "acknowledgeMassSend"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### Responses

#### HTTP 200

```json
{
  "description": "Recorded admission/outcome with separate queue, journal, reservation and stop-cleanup evidence.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/CampaignAudienceDispatchCommandResponse"
      }
    }
  }
}
```

#### HTTP 202

```json
{
  "description": "The same recorded command is still pending; no effect was replayed.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/CampaignAudienceDispatchCommandResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_UUID, INVALID_AUDIENCE_DISPATCH_INPUT or UNKNOWN_QUERY_PARAMETER: use only declared fields and the exact reviewed values.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "The API key or OAuth token is missing or invalid.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, CAMPAIGN_RESTRICTED_KEY or INVALID_ORGANISATION_CONTEXT: all required current capabilities and an open exact organisation are mandatory.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CAMPAIGN_NOT_FOUND or DISPATCH_COMMAND_NOT_FOUND: the exact campaign or same-principal command is unavailable.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "CAMPAIGN_CHANGED, SAVED_AUDIENCE_CHANGED, DISPATCH_AUDIENCE_EMPTY, CAMPAIGN_NOT_EDITABLE, CAMPAIGN_ALREADY_HAS_DELIVERIES or source/sender/media/fence conflicts. Read the command and current preview; never bypass an uncertain result with another key.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "DISPATCH_LIMIT_REACHED: at most 2000 initial rows and 16777216 queue bytes; narrow and save the audience before reviewing again.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "CAMPAIGN_DISPATCH_UNAVAILABLE: the outcome may be unknown; read the same command instead of sending again.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "DISPATCH_JOURNAL_UNCERTAIN, DISPATCH_SOURCE_UNAVAILABLE or CAMPAIGN_FENCE_UNCERTAIN: observe the same command; a missing response or ACK never authorizes replay.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "messages:send",
  "x-unisoft-additional-scopes": [
    "messages:read",
    "contacts:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "action",
    "readOnly": false,
    "destructive": false,
    "idempotent": true,
    "warn": true
  },
  "x-unisoft-conditional-scopes": [
    {
      "condition": "saved target list kind form",
      "scopes": [
        "forms:read",
        "forms_submit:read"
      ],
      "allRequired": true
    },
    {
      "condition": "saved target list kind product",
      "scopes": [
        "forms:read",
        "forms_submit:read"
      ],
      "allRequired": true
    },
    {
      "condition": "saved target list kind cagnotte",
      "scopes": [
        "caisses:read",
        "paiements:read"
      ],
      "allRequired": true
    },
    {
      "condition": "saved target list kind event",
      "scopes": [
        "events:read",
        "forms:read",
        "forms_submit:read",
        "caisses:read",
        "paiements:read"
      ],
      "allRequired": true
    },
    {
      "condition": "saved target list kind fundraising",
      "scopes": [
        "fundraising:read",
        "paiements:read",
        "abonnements:read",
        "promesses:read"
      ],
      "allRequired": true
    },
    {
      "condition": "saved emailTemplate is present",
      "scopes": [
        "email_templates:read"
      ],
      "allRequired": true
    }
  ]
}
```

## GET /campaigns/{id}/audience-dispatches/{commandId}

Observe one saved-audience dispatch command without replay

`get_campaign_audience_dispatch`

Requires current messages:read and contacts:read in the same organisation and API principal as the command; campaign-restricted keys are refused. Read the retained commandId after QUEUED, PENDING, UNCERTAIN, an HTTP error or a missing response. queueObservation/observedDeliveryCount inspect only the frozen initial UUIDs; they exclude future fallback rows and do not replace delivery-progress/delivery reads. COMPLETE does not repair an unacknowledged write or mean delivered. queueAdmission=CONFIRMED and QUEUED never establish inbox arrival or reading. The command cannot release an uncertain fence, rerender, resend, call a provider or poll transport. No query parameter or request body is accepted.

### Authentication

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Required permissions

```json
{
  "accepted": "messages:read",
  "additional": [
    "contacts:read"
  ]
}
```

### Parameters

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

```json
{
  "name": "commandId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### Responses

#### HTTP 200

```json
{
  "description": "Current recorded command and read-only evidence for its frozen initial delivery UUIDs.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/CampaignAudienceDispatchCommandResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_UUID, INVALID_AUDIENCE_DISPATCH_INPUT or UNKNOWN_QUERY_PARAMETER: use only declared fields and the exact reviewed values.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "The API key or OAuth token is missing or invalid.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, CAMPAIGN_RESTRICTED_KEY or INVALID_ORGANISATION_CONTEXT: all required current capabilities and an open exact organisation are mandatory.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CAMPAIGN_NOT_FOUND or DISPATCH_COMMAND_NOT_FOUND: the exact campaign or same-principal command is unavailable.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "CAMPAIGN_CHANGED, SAVED_AUDIENCE_CHANGED, DISPATCH_AUDIENCE_EMPTY, CAMPAIGN_NOT_EDITABLE, CAMPAIGN_ALREADY_HAS_DELIVERIES or source/sender/media/fence conflicts. Read the command and current preview; never bypass an uncertain result with another key.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "DISPATCH_LIMIT_REACHED: at most 2000 initial rows and 16777216 queue bytes; narrow and save the audience before reviewing again.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "CAMPAIGN_DISPATCH_UNAVAILABLE: the outcome may be unknown; read the same command instead of sending again.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "DISPATCH_JOURNAL_UNCERTAIN, DISPATCH_SOURCE_UNAVAILABLE or CAMPAIGN_FENCE_UNCERTAIN: observe the same command; a missing response or ACK never authorizes replay.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "messages:read",
  "x-unisoft-additional-scopes": [
    "contacts:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /campaigns/{id}/update-receipts/{commandId}

Observe one legacy campaign update receipt

`get_campaign_update_receipt`

Requires current messages:write only, matching the original legacy update grant. Read the commandId returned by PATCH /campaigns/{id} or POST /campaigns/{id}/send respectively. The exact current API principal, open organisation, campaign and persisted legacyAction=UPDATE must match. This GET is passive even though its scope is a mutation capability: no journal, native write, reservation, release, queue or provider call occurs. COMPLETED with queueAdmission=NOT_STARTED acknowledges only a draft update. QUEUED with queueAdmission=CONFIRMED acknowledges initial native queue admission, never delivery or reading. UNCERTAIN/PENDING and a complete later queue observation do not authorize another legacy POST/PATCH or repair an unknown ACK. Native write, terminal journal and fence status are separate; an unknown journal or cleanup retains the campaign fence. No contact, message content, sender configuration, journal fingerprint or token is returned. No query parameter or HTTP body is accepted.

### Authentication

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Required permissions

```json
{
  "accepted": "messages:write",
  "additional": []
}
```

### Parameters

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

```json
{
  "name": "commandId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### Responses

#### HTTP 200

```json
{
  "description": "Read-only receipt under the exact original legacy capability.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/CampaignAudienceDispatchCommandResponse"
      }
    }
  }
}
```

#### HTTP 202

```json
{
  "description": "The recorded legacy mutation remains pending; nothing was resumed.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/CampaignAudienceDispatchCommandResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_UUID, INVALID_AUDIENCE_DISPATCH_INPUT or UNKNOWN_QUERY_PARAMETER: use only declared fields and the exact reviewed values.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "The API key or OAuth token is missing or invalid.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, CAMPAIGN_RESTRICTED_KEY or INVALID_ORGANISATION_CONTEXT: all required current capabilities and an open exact organisation are mandatory.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CAMPAIGN_NOT_FOUND or DISPATCH_COMMAND_NOT_FOUND: the exact campaign or same-principal command is unavailable.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "CAMPAIGN_CHANGED, SAVED_AUDIENCE_CHANGED, DISPATCH_AUDIENCE_EMPTY, CAMPAIGN_NOT_EDITABLE, CAMPAIGN_ALREADY_HAS_DELIVERIES or source/sender/media/fence conflicts. Read the command and current preview; never bypass an uncertain result with another key.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "DISPATCH_LIMIT_REACHED: at most 2000 initial rows and 16777216 queue bytes; narrow and save the audience before reviewing again.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "CAMPAIGN_DISPATCH_UNAVAILABLE: the outcome may be unknown; read the same command instead of sending again.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "DISPATCH_JOURNAL_UNCERTAIN, DISPATCH_SOURCE_UNAVAILABLE or CAMPAIGN_FENCE_UNCERTAIN: observe the same command; a missing response or ACK never authorizes replay.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "messages:write",
  "x-unisoft-additional-scopes": [],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /campaigns/{id}/send-receipts/{commandId}

Observe one legacy campaign send receipt

`get_campaign_send_receipt`

Requires current messages:send only, matching the original legacy send grant. Read the commandId returned by PATCH /campaigns/{id} or POST /campaigns/{id}/send respectively. The exact current API principal, open organisation, campaign and persisted legacyAction=DISPATCH must match. This GET is passive even though its scope is a mutation capability: no journal, native write, reservation, release, queue or provider call occurs. COMPLETED with queueAdmission=NOT_STARTED acknowledges only a draft update. QUEUED with queueAdmission=CONFIRMED acknowledges initial native queue admission, never delivery or reading. UNCERTAIN/PENDING and a complete later queue observation do not authorize another legacy POST/PATCH or repair an unknown ACK. Native write, terminal journal and fence status are separate; an unknown journal or cleanup retains the campaign fence. No contact, message content, sender configuration, journal fingerprint or token is returned. No query parameter or HTTP body is accepted.

### Authentication

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Required permissions

```json
{
  "accepted": "messages:send",
  "additional": []
}
```

### Parameters

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

```json
{
  "name": "commandId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### Responses

#### HTTP 200

```json
{
  "description": "Read-only receipt under the exact original legacy capability.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/CampaignAudienceDispatchCommandResponse"
      }
    }
  }
}
```

#### HTTP 202

```json
{
  "description": "The recorded legacy mutation remains pending; nothing was resumed.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/CampaignAudienceDispatchCommandResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_UUID, INVALID_AUDIENCE_DISPATCH_INPUT or UNKNOWN_QUERY_PARAMETER: use only declared fields and the exact reviewed values.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "The API key or OAuth token is missing or invalid.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, CAMPAIGN_RESTRICTED_KEY or INVALID_ORGANISATION_CONTEXT: all required current capabilities and an open exact organisation are mandatory.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "CAMPAIGN_NOT_FOUND or DISPATCH_COMMAND_NOT_FOUND: the exact campaign or same-principal command is unavailable.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "CAMPAIGN_CHANGED, SAVED_AUDIENCE_CHANGED, DISPATCH_AUDIENCE_EMPTY, CAMPAIGN_NOT_EDITABLE, CAMPAIGN_ALREADY_HAS_DELIVERIES or source/sender/media/fence conflicts. Read the command and current preview; never bypass an uncertain result with another key.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "DISPATCH_LIMIT_REACHED: at most 2000 initial rows and 16777216 queue bytes; narrow and save the audience before reviewing again.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "CAMPAIGN_DISPATCH_UNAVAILABLE: the outcome may be unknown; read the same command instead of sending again.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "DISPATCH_JOURNAL_UNCERTAIN, DISPATCH_SOURCE_UNAVAILABLE or CAMPAIGN_FENCE_UNCERTAIN: observe the same command; a missing response or ACK never authorizes replay.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "messages:send",
  "x-unisoft-additional-scopes": [],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /campaigns/{id}/delivery-progress

Read recorded campaign progress by channel

`get_campaign_delivery_progress`

Requires messages:read. Read a message campaign UUID in the authenticated organisation; this is separate from a fundraising campaign. No query parameters or HTTP request body are accepted. Campaign ownership and send.organisation/groupe must be exact scalar strings under binary collation. Observe existing send rows only: true tests are excluded; malformed test flags are separately counted and excluded from non-test totals. channels contains only observed non-test channel buckets, with UNKNOWN for malformed/unsupported channel history. recordCount counts delivery rows, not people: fallback attempts create additional rows and future fallbacks do not yet exist. initialTargetCount is the stored initial dispatch count or null, never an audience preview or proof that queue construction completed. pendingCount counts INIT; scheduledPendingCount is INIT with a BSON date strictly after source.observedAt, readyOrInFlightCount is INIT with no/null/due date, and unknownSchedulePendingCount preserves invalid schedules. There is no reliable common persisted active-call state: inProgressCount is always null, never zero; readyOrInFlightCount must not be presented as actively sending. successCount is recorded SUCCESS, which for email may be SMTP acceptance only, not inbox delivery or reading. failureCount includes ERROR with an uncertain outcome. canceledCount includes CANCELED/CANCELLED, including simulations. Unknown states remain unknownStateCount. deliveryUncertainCount and simulationCount are overlays, not additional disjoint outcomes; absence of an uncertainty marker does not prove safe retry. FINISHED and 100% recorded success do not prove delivery or queue completeness. source.readAt dates this read, computedAt is null, and concurrent updates may occur. Empty channels/totals describe no observed non-test queue rows, not a zero intended audience. No audience calculation, enqueue, provider call, retry, stop, reconciliation or business write occurs; authentication may record API-key usage. A missing/deleted/foreign campaign returns 404. PROGRESS_LIMIT_REACHED (503) means the bounded database observation could not complete: repeat a read later, never resend the campaign to fix it. Use the delivery-and-audiences reference for interpretation and supported recovery; uncertain dispatch outcomes never authorise automatic resend or duplication.

### Authentication

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Required permissions

```json
{
  "accepted": "messages:read",
  "additional": []
}
```

### Parameters

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "description": "UUID of an existing organisation-owned message campaign, not a fundraising campaign.",
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### Responses

#### HTTP 200

```json
{
  "description": "Qualified recorded progress; in-flight work and queue completeness remain explicit unknowns.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/CampaignDeliveryProgressResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid UUID, unknown query parameter or unexpected request body.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid API key.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "messages:read is required.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Campaign absent, deleted or outside the authenticated organisation.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "Progress could not be read; no delivery action was attempted.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "PROGRESS_LIMIT_REACHED: repeat the read later; do not resend or duplicate the campaign.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "messages:read",
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /campaigns/{id}/deliveries

List recorded deliveries and recipient snapshots

`list_campaign_deliveries`

Requires messages:read and contacts:read. Read existing non-test send rows for one organisation-owned message campaign; campaign and send organisation/group references require exact scalar strings. True tests and malformed test flags are excluded. Each row is one delivery attempt, not a unique person; fallback can create another row. INIT can be waiting, scheduled or actively calling a provider. SUCCESS is the recorded transport result, not guaranteed inbox delivery or reading. For email, ACCEPTED means SMTP accepted; DELIVERED is a stored positive delivery report. WhatsApp acknowledgements are recorded observations only. Dates are ISO instants from BSON dates, otherwise null. recipient fields are historical send snapshots. A stored contact UUID is re-admitted against a current non-deleted contact in this organisation before returning its identity; invalid/deleted/foreign references mask all identity fields as UNAVAILABLE. An absent contact reference is SNAPSHOT_ONLY, never a newly inferred CRM match. Do not use snapshot coordinates as permission to send again. reasonCode is an allowlisted code only: unknown reasons remain null, without raw errorMessage, SMTP fields, private tokens or provider IDs. deliveryUncertain:true is explicit evidence; null is not proof of safe retry. CANCELED/CANCELLED normalise to CANCELED, unsupported state/channel history becomes UNKNOWN, and no provider is queried. No enqueue, retry, reconciliation or business write occurs; authentication may record key usage. Concurrent changes may occur between reads. Missing/deleted/foreign campaign or unavailable requested contact/delivery gives 404. Repeat a read after PROGRESS_LIMIT_REACHED (503); never resend or duplicate to resolve uncertainty. Optional channel, state and contactId filters combine. contactId must currently belong to this organisation. limit is 1–200, default 50. cursor is opaque and bound to the organisation, campaign and filters; it follows delivery UUID binary order, not chronological order. Keep filters unchanged for continuation. Each filtered source is bounded to 10000 rows; a larger source returns 422 DELIVERY_SOURCE_LIMIT_EXCEEDED without partial rows, so narrow filters or read a known delivery UUID. Invalid or duplicate selected delivery UUIDs give 409 DELIVERY_HISTORY_REVIEW_REQUIRED, including on continuation. Unknown query parameters, repeated values and HTTP bodies are rejected.

### Authentication

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Required permissions

```json
{
  "accepted": "messages:read",
  "additional": [
    "contacts:read"
  ]
}
```

### Parameters

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "description": "UUID of an existing organisation-owned message campaign, not a fundraising campaign.",
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

```json
{
  "name": "channel",
  "in": "query",
  "schema": {
    "type": "string",
    "enum": [
      "EMAIL",
      "SMS",
      "WHATSAPP",
      "NOTIFICATION",
      "APPMOBILE_NOTIFICATION",
      "UNKNOWN"
    ]
  }
}
```

```json
{
  "name": "state",
  "in": "query",
  "schema": {
    "type": "string",
    "enum": [
      "INIT",
      "SUCCESS",
      "ERROR",
      "CANCELED",
      "UNKNOWN"
    ]
  }
}
```

```json
{
  "name": "contactId",
  "in": "query",
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

```json
{
  "name": "limit",
  "in": "query",
  "schema": {
    "type": "integer",
    "minimum": 1,
    "maximum": 200,
    "default": 50
  }
}
```

```json
{
  "name": "cursor",
  "in": "query",
  "schema": {
    "type": "string",
    "minLength": 1,
    "maxLength": 1024
  }
}
```

### Responses

#### HTTP 200

```json
{
  "description": "Stored recipient delivery observations with redacted unsafe identity and explicit unknowns.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/CampaignDeliveryListResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid UUID, unsupported filter, invalid cursor, unknown parameter or unexpected request body.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid API key.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Both messages:read and contacts:read are required.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Campaign, requested delivery or requested contact absent, deleted or outside the authenticated organisation.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "DELIVERY_HISTORY_REVIEW_REQUIRED: invalid or duplicate delivery IDs require supported operator review; no fabricated IDs or partial page is returned.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "DELIVERY_SOURCE_LIMIT_EXCEEDED: select a channel, state or contact to reduce the source below 10000 rows.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "Delivery observations could not be read; no delivery action was attempted.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "PROGRESS_LIMIT_REACHED: repeat the read later; do not resend or duplicate the campaign.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "messages:read",
  "x-unisoft-additional-scopes": [
    "contacts:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /campaigns/{id}/deliveries/{deliveryId}

Read one recorded campaign delivery

`get_campaign_delivery`

Requires messages:read and contacts:read. Read existing non-test send rows for one organisation-owned message campaign; campaign and send organisation/group references require exact scalar strings. True tests and malformed test flags are excluded. Each row is one delivery attempt, not a unique person; fallback can create another row. INIT can be waiting, scheduled or actively calling a provider. SUCCESS is the recorded transport result, not guaranteed inbox delivery or reading. For email, ACCEPTED means SMTP accepted; DELIVERED is a stored positive delivery report. WhatsApp acknowledgements are recorded observations only. Dates are ISO instants from BSON dates, otherwise null. recipient fields are historical send snapshots. A stored contact UUID is re-admitted against a current non-deleted contact in this organisation before returning its identity; invalid/deleted/foreign references mask all identity fields as UNAVAILABLE. An absent contact reference is SNAPSHOT_ONLY, never a newly inferred CRM match. Do not use snapshot coordinates as permission to send again. reasonCode is an allowlisted code only: unknown reasons remain null, without raw errorMessage, SMTP fields, private tokens or provider IDs. deliveryUncertain:true is explicit evidence; null is not proof of safe retry. CANCELED/CANCELLED normalise to CANCELED, unsupported state/channel history becomes UNKNOWN, and no provider is queried. No enqueue, retry, reconciliation or business write occurs; authentication may record key usage. Concurrent changes may occur between reads. Missing/deleted/foreign campaign or unavailable requested contact/delivery gives 404. Repeat a read after PROGRESS_LIMIT_REACHED (503); never resend or duplicate to resolve uncertainty. deliveryId is the exact stored delivery UUID under this campaign. No query parameter or HTTP body is accepted. A duplicate delivery UUID returns 409 DELIVERY_HISTORY_REVIEW_REQUIRED rather than choosing an arbitrary record. This is not a receipt polling or resend operation.

### Authentication

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Required permissions

```json
{
  "accepted": "messages:read",
  "additional": [
    "contacts:read"
  ]
}
```

### Parameters

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "description": "UUID of an existing organisation-owned message campaign, not a fundraising campaign.",
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

```json
{
  "name": "deliveryId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### Responses

#### HTTP 200

```json
{
  "description": "Stored recipient delivery observations with redacted unsafe identity and explicit unknowns.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/CampaignDeliveryRecordResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid UUID, unsupported filter, invalid cursor, unknown parameter or unexpected request body.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid API key.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Both messages:read and contacts:read are required.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Campaign, requested delivery or requested contact absent, deleted or outside the authenticated organisation.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "DELIVERY_HISTORY_REVIEW_REQUIRED: invalid or duplicate delivery IDs require supported operator review; no fabricated IDs or partial page is returned.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "DELIVERY_SOURCE_LIMIT_EXCEEDED: select a channel, state or contact to reduce the source below 10000 rows.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "Delivery observations could not be read; no delivery action was attempted.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "PROGRESS_LIMIT_REACHED: repeat the read later; do not resend or duplicate the campaign.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "messages:read",
  "x-unisoft-additional-scopes": [
    "contacts:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /campaigns/{id}/stop-preview

Review recorded campaign stop preconditions

`preview_campaign_stop`

Requires messages:read. Read an exact scalar organisation-owned message campaign and count currently stored INIT delivery rows, including tests, without business writes. Returns the campaign revision required by stop_campaign, the current stop marker and pendingRecordCount. INIT can include a provider call already in flight: activeProviderCalls stays UNKNOWN and the preview never guarantees recall. A draft INIT can also be closed by an explicitly authorised stop. The preview does not reserve rows and concurrent changes may alter the count or revision. This messages:read-only preview does not assess rescheduling eligibility: rescheduleAvailable is null. Use preview_campaign_rescheduling with its own messages:reschedule, messages:read and messages:send capabilities for the bounded future queue workflow; changing only the campaign schedule would not reschedule existing rows. No query parameters or HTTP body are accepted. Missing/deleted/foreign campaigns give 404; unsupported state or ambiguous history gives 409. This read neither stops nor sends any message.

### Authentication

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Required permissions

```json
{
  "accepted": "messages:read",
  "additional": []
}
```

### Parameters

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "description": "UUID of the organisation-owned message campaign.",
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### Responses

#### HTTP 200

```json
{
  "description": "Current stop preconditions and revision; no cancellation performed.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/CampaignStopPreviewResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid UUID or envelope, unknown query/body field, malformed revision or idempotency key.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid API key.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Required campaign capabilities are missing.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Campaign or command unavailable in the authenticated organisation.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Revision/idempotency conflict or unsupported/ambiguous stored campaign history. Read current state; do not resend.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "The request could not complete. Read the existing command and campaign before another action.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "COMMAND_JOURNAL_UNAVAILABLE: outcome may require reading the same command; no new send or duplication is authorised.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "messages:read",
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /campaigns/{id}/stop

Stop a campaign and mark remaining queued rows canceled

`stop_campaign`

Requires messages:send and messages:read and an explicit user request to stop this campaign. First read preview_campaign_stop and use its exact expectedRevision. Supply a stable 8–128 character idempotencyKey and acknowledgeInFlight:true. This real mutation reproduces the native stop contract under exact scalar organisation/id/group/state guards: record FINISHED, dispatchStopped:true, stoppedAt/stoppedBy and USER_EMERGENCY_STOP before marking only current INIT rows CANCELED with canceledAt and the same reason. Tests are included. SUCCESS/ERROR rows are preserved. Existing workers check the durable stop marker before future provider calls and fallback insertion; calls already handed off may still finish and their actual result may supersede a canceled observation. No recall or exact count of prevented deliveries is promised. canceledRecordCount is the number of rows modified by this cancellation observation, not guaranteed non-deliveries. remainingPendingRecordCount is a later bounded read and can change after it. The positively acknowledged durable command journal precedes every business effect and the monotone common stop latch. STOP preempts another retained campaign mutation without stealing its owner. A missing or contradictory own journal ACK permits neither latch nor native stop effects; a 503 must not be called queue cancellation. After own journal admission, an unavailable coordination latch does not suppress the native stop attempt and is qualified separately. A repeated key with identical campaign/intent returns the same receipt without replaying effects; a changed intent gives 409 IDEMPOTENCY_CONFLICT. COMPLETED means these stop operations were acknowledged and no pending row remained at observation, PARTIAL means a residual INIT population or an uncertain coordination latch was observed, REJECTED means admission/preflight failed, RUNNING/ADMITTING is unfinished, and UNKNOWN means an effect or its verification could not be established. stopRecorded:true is observed stop evidence, not proof of provider cancellation. Read get_campaign_delivery_command after a lost response; do not resend or duplicate a campaign. No query parameters are accepted. No rescheduling, provider call, billing or enqueue occurs; authentication may record key usage.

### Authentication

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Required permissions

```json
{
  "accepted": "messages:send",
  "additional": [
    "messages:read"
  ]
}
```

### Parameters

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "description": "UUID of the organisation-owned message campaign.",
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### Request body

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "idempotencyKey": {
            "type": "string",
            "minLength": 8,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9._:-]{8,128}$"
          },
          "expectedRevision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "acknowledgeInFlight": {
            "type": "boolean",
            "enum": [
              true
            ]
          }
        },
        "required": [
          "idempotencyKey",
          "expectedRevision",
          "acknowledgeInFlight"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### Responses

#### HTTP 200

```json
{
  "description": "Durable stop command receipt; inspect state and uncertainty, not only success.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/CampaignDeliveryCommandResponse"
      }
    }
  }
}
```

#### HTTP 202

```json
{
  "description": "The same durable command is still admitted or running; no replay was performed.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/CampaignDeliveryCommandResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid UUID or envelope, unknown query/body field, malformed revision or idempotency key.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid API key.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Required campaign capabilities are missing.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Campaign or command unavailable in the authenticated organisation.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Revision/idempotency conflict or unsupported/ambiguous stored campaign history. Read current state; do not resend.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "The request could not complete. Read the existing command and campaign before another action.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "COMMAND_JOURNAL_UNAVAILABLE: outcome may require reading the same command; no new send or duplication is authorised.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "messages:send",
  "x-unisoft-additional-scopes": [
    "messages:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "write",
    "readOnly": false,
    "destructive": true,
    "idempotent": true,
    "warn": true
  }
}
```

## GET /campaigns/{id}/delivery-commands/{commandId}

Read a durable campaign delivery command receipt

`get_campaign_delivery_command`

Requires messages:read. Read an existing command UUID under this exact organisation-owned message campaign. Both campaign and journal references are re-admitted as exact scalar values. Returns the recorded command result only; ADMITTING/RUNNING/UNKNOWN must not be treated as failure or permission for a new send. stopRecorded and cancellation counts do not establish recall of provider calls already in flight. The read neither resumes nor repeats an effect and never queries a provider. Missing/deleted/foreign campaign or command gives 404. No query parameters or HTTP body are accepted.

### Authentication

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Required permissions

```json
{
  "accepted": "messages:read",
  "additional": []
}
```

### Parameters

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "description": "UUID of the organisation-owned message campaign.",
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

```json
{
  "name": "commandId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### Responses

#### HTTP 200

```json
{
  "description": "Recorded durable command receipt; no action was replayed.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/CampaignDeliveryCommandResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid UUID or envelope, unknown query/body field, malformed revision or idempotency key.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid API key.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Required campaign capabilities are missing.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Campaign or command unavailable in the authenticated organisation.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Revision/idempotency conflict or unsupported/ambiguous stored campaign history. Read current state; do not resend.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "The request could not complete. Read the existing command and campaign before another action.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "COMMAND_JOURNAL_UNAVAILABLE: outcome may require reading the same command; no new send or duplication is authorised.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "messages:read",
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /campaigns/{id}/audience-preview

Preview a CRM audience and previous campaign exclusions

`preview_campaign_audience`

target.allContact:true explicitly starts from all visible non-deleted contacts; listIds/categories must be empty and operator must be union, while excludedListIds/excludedCategories refine that base. Omit allContact for the existing positive list/category mode. Requires messages:read and contacts:read. Resolve a proposed CRM-list/category audience for an INIT message draft through the native audience owner, without sending or creating queue rows. target.version is 1; choose union/intersection of nonempty listIds and/or categories, with optional excludedListIds/excludedCategories. Exact category labels are case-sensitive. Resolve exact list IDs using list_contact_lists and require availableForSearch:true. Canonical CRM list IDs are: form:<form UUID>, product:<form UUID>:<product UUID>, cagnotte:<caisse UUID>, event:<session UUID> or fundraising:<fundraising UUID>. Never guess the UUIDs; a known source UUID alone does not prove its list is published in the current generation. Source scopes are additional and checked before reads: form/product require forms:read + forms_submit:read; cagnotte requires caisses:read + paiements:read; event requires events:read + forms:read + forms_submit:read + caisses:read + paiements:read; fundraising requires fundraising:read + paiements:read + abonnements:read + promesses:read. The owner receives only API_KEY capabilities derived from those granted scopes, never ADMIN or all. Campaign-restricted keys are refused rather than widening unrelated source access. Current source ownership, generation, list identity, contact/parent references and previous campaign references are re-admitted; malformed history gives an explicit refusal, never an empty or widened audience. Each source read is bounded to 20000 rows and 10000 ms. Previous-campaign exclusions match recorded non-test SUCCESS rows and stored coordinates/contact references, not confirmed inbox delivery. A deleted previous campaign keeps its exclusion significance. An unavailable exclusion blocks rather than silently reincluding recipients. Contacts, parent substitution, reachable channels, unsubscribes, deduplication and fallbacks use the native owner; preparedRecordCount is prepared recipient rows at this observation, not guaranteed deliveries, money cost or future fallback count. No recipient PII is returned. A zero preview is valid but cannot be saved as a ready audience. Imported, submission-guided or annual-event audiences are preserved and refused rather than silently replaced. The response gives the current draft revision and audienceHash for save_campaign_audience. It does not reserve that population. After saving the audience, explicitly authorised mass dispatch uses preview_saved_campaign_dispatch and dispatch_saved_campaign_audience with messages:send and their own current preflight. Existing send_campaign still refuses CRM-list drafts. No provider call or business write occurs during preview; authentication may record key usage. No query parameters are accepted.

### Authentication

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Required permissions

```json
{
  "accepted": "messages:read",
  "additional": [
    "contacts:read"
  ]
}
```

### Parameters

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "description": "UUID of the organisation-owned message campaign.",
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### Request body

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "target": {
            "$ref": "#/components/schemas/UnisoftRequest_46ebc7072c9dc383fded"
          },
          "excludedCampaignIds": {
            "type": "array",
            "maxItems": 100,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "format": "uuid"
            }
          }
        },
        "required": [
          "target"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### Responses

#### HTTP 200

```json
{
  "description": "Current qualified audience preview; no recipients enqueued.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/CampaignAudiencePreviewResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid UUID or envelope, unknown query/body field, malformed revision or idempotency key.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid API key.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Required campaign capabilities are missing.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Campaign or command unavailable in the authenticated organisation.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Revision/idempotency conflict or unsupported/ambiguous stored campaign history. Read current state; do not resend.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "AUDIENCE_SOURCE_LIMIT: narrow the source selection; no partial audience is returned.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "The request could not complete. Read the existing command and campaign before another action.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "AUDIENCE_SOURCE_UNAVAILABLE: repeat the bounded read later; do not send to recover a preview.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-additional-scopes": [
    "contacts:read"
  ],
  "x-unisoft-conditional-scopes": [
    {
      "condition": "target list kind form",
      "scopes": [
        "forms:read",
        "forms_submit:read"
      ],
      "allRequired": true
    },
    {
      "condition": "target list kind product",
      "scopes": [
        "forms:read",
        "forms_submit:read"
      ],
      "allRequired": true
    },
    {
      "condition": "target list kind cagnotte",
      "scopes": [
        "caisses:read",
        "paiements:read"
      ],
      "allRequired": true
    },
    {
      "condition": "target list kind event",
      "scopes": [
        "events:read",
        "forms:read",
        "forms_submit:read",
        "caisses:read",
        "paiements:read"
      ],
      "allRequired": true
    },
    {
      "condition": "target list kind fundraising",
      "scopes": [
        "fundraising:read",
        "paiements:read",
        "abonnements:read",
        "promesses:read"
      ],
      "allRequired": true
    }
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-scope": "messages:read",
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## PATCH /campaigns/{id}/audience

Save a reviewed CRM audience on a draft without sending

`save_campaign_audience`

target.allContact:true explicitly starts from all visible non-deleted contacts; listIds/categories must be empty and operator must be union, while excludedListIds/excludedCategories refine that base. Omit allContact for the existing positive list/category mode. Requires messages:read and contacts:read. Resolve a proposed CRM-list/category audience for an INIT message draft through the native audience owner, without sending or creating queue rows. target.version is 1; choose union/intersection of nonempty listIds and/or categories, with optional excludedListIds/excludedCategories. Exact category labels are case-sensitive. Resolve exact list IDs using list_contact_lists and require availableForSearch:true. Canonical CRM list IDs are: form:<form UUID>, product:<form UUID>:<product UUID>, cagnotte:<caisse UUID>, event:<session UUID> or fundraising:<fundraising UUID>. Never guess the UUIDs; a known source UUID alone does not prove its list is published in the current generation. Source scopes are additional and checked before reads: form/product require forms:read + forms_submit:read; cagnotte requires caisses:read + paiements:read; event requires events:read + forms:read + forms_submit:read + caisses:read + paiements:read; fundraising requires fundraising:read + paiements:read + abonnements:read + promesses:read. The owner receives only API_KEY capabilities derived from those granted scopes, never ADMIN or all. Campaign-restricted keys are refused rather than widening unrelated source access. Current source ownership, generation, list identity, contact/parent references and previous campaign references are re-admitted; malformed history gives an explicit refusal, never an empty or widened audience. Each source read is bounded to 20000 rows and 10000 ms. Previous-campaign exclusions match recorded non-test SUCCESS rows and stored coordinates/contact references, not confirmed inbox delivery. A deleted previous campaign keeps its exclusion significance. An unavailable exclusion blocks rather than silently reincluding recipients. Contacts, parent substitution, reachable channels, unsubscribes, deduplication and fallbacks use the native owner; preparedRecordCount is prepared recipient rows at this observation, not guaranteed deliveries, money cost or future fallback count. No recipient PII is returned. A zero preview is valid but cannot be saved as a ready audience. Imported, submission-guided or annual-event audiences are preserved and refused rather than silently replaced. The response gives the current draft revision and audienceHash for save_campaign_audience. It does not reserve that population. After saving the audience, explicitly authorised mass dispatch uses preview_saved_campaign_dispatch and dispatch_saved_campaign_audience with messages:send and their own current preflight. Existing send_campaign still refuses CRM-list drafts. No provider call or business write occurs during preview; authentication may record key usage. No query parameters are accepted. Saving additionally requires messages:write. First obtain a preview, then provide its exact expectedRevision and audienceHash with the same target/exclusions and a stable idempotencyKey. The owner resolves the audience again immediately before the CAS write. A changed revision/hash or empty population gives a durable REJECTED receipt. COMPLETED with selectionSaved:true means only the CRM target, exclusions and summary were saved on the unchanged INIT draft; no message was sent. The same key returns its recorded receipt without another write; UNKNOWN preserves a lost write result. Read get_campaign_delivery_command after a lost response. Preserve unrelated content and specialised audiences. The common campaign mutation fence coordinates audience save, update, dispatch and future rescheduling. Only a positive native write plus a positive terminal journal permits release; an uncertain result retains the fence. To send the saved CRM audience, obtain preview_saved_campaign_dispatch and explicitly authorise dispatch_saved_campaign_audience. Do not clear crmTarget or call legacy send_campaign to bypass that review.

### Authentication

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Required permissions

```json
{
  "accepted": "messages:write",
  "additional": [
    "messages:read",
    "contacts:read"
  ]
}
```

### Parameters

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "description": "UUID of the organisation-owned message campaign.",
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### Request body

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "target": {
            "$ref": "#/components/schemas/UnisoftRequest_46ebc7072c9dc383fded"
          },
          "excludedCampaignIds": {
            "type": "array",
            "maxItems": 100,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "format": "uuid"
            }
          },
          "expectedRevision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "audienceHash": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "idempotencyKey": {
            "type": "string",
            "minLength": 8,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9._:-]{8,128}$"
          }
        },
        "required": [
          "target",
          "expectedRevision",
          "audienceHash",
          "idempotencyKey"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### Responses

#### HTTP 200

```json
{
  "description": "Durable audience-save receipt; no dispatch occurred.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/CampaignDeliveryCommandResponse"
      }
    }
  }
}
```

#### HTTP 202

```json
{
  "description": "The same audience command is still admitted or running; no write was replayed.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/CampaignDeliveryCommandResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid UUID or envelope, unknown query/body field, malformed revision or idempotency key.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid API key.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Required campaign capabilities are missing.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Campaign or command unavailable in the authenticated organisation.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Revision/idempotency conflict or unsupported/ambiguous stored campaign history. Read current state; do not resend.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "AUDIENCE_SOURCE_LIMIT: narrow the source selection; no partial audience is returned.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "The request could not complete. Read the existing command and campaign before another action.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "COMMAND_JOURNAL_UNAVAILABLE: outcome may require reading the same command; no new send or duplication is authorised.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-additional-scopes": [
    "messages:read",
    "contacts:read"
  ],
  "x-unisoft-conditional-scopes": [
    {
      "condition": "target list kind form",
      "scopes": [
        "forms:read",
        "forms_submit:read"
      ],
      "allRequired": true
    },
    {
      "condition": "target list kind product",
      "scopes": [
        "forms:read",
        "forms_submit:read"
      ],
      "allRequired": true
    },
    {
      "condition": "target list kind cagnotte",
      "scopes": [
        "caisses:read",
        "paiements:read"
      ],
      "allRequired": true
    },
    {
      "condition": "target list kind event",
      "scopes": [
        "events:read",
        "forms:read",
        "forms_submit:read",
        "caisses:read",
        "paiements:read"
      ],
      "allRequired": true
    },
    {
      "condition": "target list kind fundraising",
      "scopes": [
        "fundraising:read",
        "paiements:read",
        "abonnements:read",
        "promesses:read"
      ],
      "allRequired": true
    }
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-scope": "messages:write",
  "x-unisoft-mcp": {
    "category": "update",
    "readOnly": false,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /campaigns/{id}/sms-preview

Estimate draft SMS segments and observe remaining quota

`preview_campaign_sms_usage`

Requires messages:read and contacts:read. Read an unchanged INIT message draft with a saved explicit ordinary audience (allContact, starred or categories) or saved crmTarget. Special imported/form/annual-event audiences are not broadened to perform this estimate. A saved CRM target also needs the source scopes described by preview_campaign_audience; restricted campaign keys are refused. Supply an empty JSON object, no query parameters. The native audience resolver, parent substitution, unsubscribe handling, deduplication and fallback preparation are reused without saving or creating send rows. primaryRecordCount/primarySegments count eligible INIT primary SMS rows; ineligibleSmsRecordCount counts SMS rows already prepared ERROR and excluded from the estimate. possibleFallbackRecordCount/possibleFallbackSegments describe only the potential SMS fallback of eligible primary rows on another channel, not promised dispatch or additional guaranteed consumption. Do not add them to primarySegments and call that a binding quote. Each personalised stored preparation text is stripped with the worker messageRemoveWhatsappTags and measured with the same gsm package; groups split GSM_03_38 and UNICODE. Texts total at most 16 MiB and source reads at most 20000 rows/10000 ms. Provider-added content, future edits, availability and actual billing can change consumption; source.estimateOnly is true and no provider is queried. quota.remainingCredits is a qualified legacy CRM.getNbSMSAvailable observation in SMS_SEGMENT_CREDIT, not money or a reservation. Sources are preflighted for exact ownership and safe types; unreadable/invalid/oversized quota history or a failed quota owner yields null without hiding a usable segment estimate. The legacy getter has known provider-adjustment projection limitations, so sufficientForPrimaryEstimate compares only that observation with the primary estimate and never guarantees capacity. Negative observed credits remain negative. No canonical monetary tariff is available: pricing.amountMinor and currency remain null, not zero/free. No send, debit, quota reservation, campaign edit or reconciliation occurs; authentication may record key usage. SMS_AUDIENCE_REQUIRED asks for an explicit supported saved selection; do not send to discover cost. A limit refusal requires narrowing/reviewing the selection, never partial totals or an automatic send. When the SMS platform is active, the optional sms object is the applicable estimate in Unisoft units. It includes maximum units if every potential SMS fallback is used, rows on external funding, unavailable rows and the observed wallet. No recipient coordinates or message content are returned. For send_campaign on an ordinary draft, confirm the units with the user and pass sms.estimateHash as smsEstimateHash. For a saved CRM audience, obtain the dispatch-specific hash from preview_saved_campaign_dispatch; the segment-only and legacy quota fields here are for observation.

### Authentication

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Required permissions

```json
{
  "accepted": "messages:read",
  "additional": [
    "contacts:read"
  ]
}
```

### Parameters

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "description": "UUID of the organisation-owned message campaign.",
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### Request body

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {},
        "additionalProperties": false
      }
    }
  }
}
```

### Responses

#### HTTP 200

```json
{
  "description": "Qualified segment estimate and nullable legacy quota observation; no reservation or monetary quote.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/CampaignSmsPreviewResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid UUID or envelope, unknown query/body field, malformed revision or idempotency key.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid API key.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Required campaign capabilities are missing.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Campaign or command unavailable in the authenticated organisation.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Revision/idempotency conflict or unsupported/ambiguous stored campaign history. Read current state; do not resend.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 422

```json
{
  "description": "SMS_PREVIEW_SOURCE_LIMIT or AUDIENCE_SOURCE_LIMIT: narrow the selection; no partial estimate returned.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "The request could not complete. Read the existing command and campaign before another action.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "COMMAND_JOURNAL_UNAVAILABLE: outcome may require reading the same command; no new send or duplication is authorised.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-additional-scopes": [
    "contacts:read"
  ],
  "x-unisoft-conditional-scopes": [
    {
      "condition": "target list kind form",
      "scopes": [
        "forms:read",
        "forms_submit:read"
      ],
      "allRequired": true
    },
    {
      "condition": "target list kind product",
      "scopes": [
        "forms:read",
        "forms_submit:read"
      ],
      "allRequired": true
    },
    {
      "condition": "target list kind cagnotte",
      "scopes": [
        "caisses:read",
        "paiements:read"
      ],
      "allRequired": true
    },
    {
      "condition": "target list kind event",
      "scopes": [
        "events:read",
        "forms:read",
        "forms_submit:read",
        "caisses:read",
        "paiements:read"
      ],
      "allRequired": true
    },
    {
      "condition": "target list kind fundraising",
      "scopes": [
        "fundraising:read",
        "paiements:read",
        "abonnements:read",
        "promesses:read"
      ],
      "allRequired": true
    }
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-scope": "messages:read",
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /campaigns/{id}/template-send-preview

Review one independent template email before sending

`preview_template_message_send`

Requires messages:read, contacts:read and email_templates:read. Prepare one independent EMAIL to one current non-deceased organisation-owned CRM contact from one current organisation-owned local email template. This supports email only, not WhatsApp/SMS template sending. An existing INIT message draft UUID is used solely as the command context; its saved mass audience, content and state are not dispatched or changed. Stopped or started contexts are refused. Supply the exact contactId, templateId and nonempty subject, plus an optional organisation-owned emailConfigId. The recipient email is normalised from the current contact, never taken as a caller-supplied raw address. Current mailing unsubscribes are checked and cannot be bypassed with this operation. Exact scalar ownership and duplicate/ambiguous references are checked before the native sender. The preview returns recipientEmail and a revision tied to the current contact/template/subject/context. Review the selected template through its read operation when content matters. It is not frozen: the native owner reloads current template HTML at enqueue and configuration can change before worker delivery. No provider call or test message occurs in preview. A campaign draft request or this preview does not authorise a real send. Campaign-restricted keys are refused; unknown body/query fields and malformed references are rejected.

### Authentication

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Required permissions

```json
{
  "accepted": "messages:read",
  "additional": [
    "contacts:read",
    "email_templates:read"
  ]
}
```

### Parameters

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "description": "UUID of the organisation-owned message campaign.",
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### Request body

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "contactId": {
            "type": "string",
            "format": "uuid"
          },
          "templateId": {
            "type": "string",
            "format": "uuid"
          },
          "subject": {
            "type": "string",
            "minLength": 1,
            "maxLength": 500
          },
          "emailConfigId": {
            "type": "string",
            "format": "uuid"
          }
        },
        "required": [
          "contactId",
          "templateId",
          "subject"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### Responses

#### HTTP 200

```json
{
  "description": "Current individual email intent and revision; no enqueue or provider call.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/CampaignTemplateSendPreviewResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid UUID or envelope, unknown query/body field, malformed revision or idempotency key.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid API key.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Required campaign capabilities are missing.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Campaign or command unavailable in the authenticated organisation.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Revision/idempotency conflict or unsupported/ambiguous stored campaign history. Read current state; do not resend.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "The request could not complete. Read the existing command and campaign before another action.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "COMMAND_JOURNAL_UNAVAILABLE: outcome may require reading the same command; no new send or duplication is authorised.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "messages:read",
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  },
  "x-unisoft-additional-scopes": [
    "contacts:read",
    "email_templates:read"
  ]
}
```

## POST /campaigns/{id}/template-sends

Queue one authorised independent template email

`send_template_message`

Requires messages:read, contacts:read and email_templates:read. Prepare one independent EMAIL to one current non-deceased organisation-owned CRM contact from one current organisation-owned local email template. This supports email only, not WhatsApp/SMS template sending. An existing INIT message draft UUID is used solely as the command context; its saved mass audience, content and state are not dispatched or changed. Stopped or started contexts are refused. Supply the exact contactId, templateId and nonempty subject, plus an optional organisation-owned emailConfigId. The recipient email is normalised from the current contact, never taken as a caller-supplied raw address. Current mailing unsubscribes are checked and cannot be bypassed with this operation. Exact scalar ownership and duplicate/ambiguous references are checked before the native sender. The preview returns recipientEmail and a revision tied to the current contact/template/subject/context. Review the selected template through its read operation when content matters. It is not frozen: the native owner reloads current template HTML at enqueue and configuration can change before worker delivery. No provider call or test message occurs in preview. A campaign draft request or this preview does not authorise a real send. Campaign-restricted keys are refused; unknown body/query fields and malformed references are rejected. Sending additionally requires messages:send and explicit user direction for this one template, subject and recipient. Obtain preview_template_message_send first; pass the same intent, exact expectedRevision, stable idempotencyKey and acknowledgeIndependentSend:true. The durable journal and globally unique source are written before calling native sendMailOrg once. Its missing return ID is not interpreted as failure: the adapter always reads that exact source in the same organisation, even after an owner exception. QUEUED with deliveryId means one matching email row was observed, never delivery, SMTP acceptance, reading or reply. A missing/ambiguous/unreadable row leaves UNKNOWN; never automatically retry with another key or create a substitute send. Repeating an identical key returns the same receipt without another owner call; a changed intent gives IDEMPOTENCY_CONFLICT. Read get_campaign_delivery_command and get_template_message_delivery after a lost response. The individual queue row has no broadcast group, so it does not appear in campaign progress/counts or stop/finish that draft; it is a separate real email, not test_campaign. Organisation email configuration is preferred through the native owner with its normal fallback. No synchronous provider call is made here, but the queued worker will send a real email. The operation does not reserve the template or SMTP configuration.

### Authentication

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Required permissions

```json
{
  "accepted": "messages:send",
  "additional": [
    "messages:read",
    "contacts:read",
    "email_templates:read"
  ]
}
```

### Parameters

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "description": "UUID of the organisation-owned message campaign.",
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### Request body

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "contactId": {
            "type": "string",
            "format": "uuid"
          },
          "templateId": {
            "type": "string",
            "format": "uuid"
          },
          "subject": {
            "type": "string",
            "minLength": 1,
            "maxLength": 500
          },
          "emailConfigId": {
            "type": "string",
            "format": "uuid"
          },
          "expectedRevision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "idempotencyKey": {
            "type": "string",
            "minLength": 8,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9._:-]{8,128}$"
          },
          "acknowledgeIndependentSend": {
            "type": "boolean",
            "enum": [
              true
            ]
          }
        },
        "required": [
          "contactId",
          "templateId",
          "subject",
          "expectedRevision",
          "idempotencyKey",
          "acknowledgeIndependentSend"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### Responses

#### HTTP 200

```json
{
  "description": "Durable enqueue command receipt: inspect QUEUED, REJECTED or UNKNOWN; queued is not delivered.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/CampaignDeliveryCommandResponse"
      }
    }
  }
}
```

#### HTTP 202

```json
{
  "description": "The same durable template-send command is still admitted/running; no owner call replayed.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/CampaignDeliveryCommandResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid UUID or envelope, unknown query/body field, malformed revision or idempotency key.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid API key.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Required campaign capabilities are missing.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Campaign or command unavailable in the authenticated organisation.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Revision/idempotency conflict or unsupported/ambiguous stored campaign history. Read current state; do not resend.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "The request could not complete. Read the existing command and campaign before another action.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "COMMAND_JOURNAL_UNAVAILABLE: outcome may require reading the same command; no new send or duplication is authorised.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "messages:send",
  "x-unisoft-additional-scopes": [
    "messages:read",
    "contacts:read",
    "email_templates:read"
  ],
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "action",
    "readOnly": false,
    "destructive": false,
    "idempotent": true,
    "warn": true
  }
}
```

## GET /campaigns/{id}/template-sends/{commandId}/delivery

Read the recorded outcome of one independent template email

`get_template_message_delivery`

Requires messages:read and contacts:read. Read the exact send row bound to an existing SEND_TEMPLATE command UUID under this organisation-owned campaign context. It can resolve later queue evidence even when the enqueue receipt remains UNKNOWN; it does not resume or resend anything. The source is recomputed from the command identity and checked with exact organisation/source/channel/destination ownership; absent or ambiguous queue evidence gives TEMPLATE_DELIVERY_UNAVAILABLE (409), not non-delivery. The current contact reference is re-admitted before publishing the historical email snapshot; a deleted/foreign reference masks identity. State, timestamps, safe reason code and email receipt status follow get_campaign_delivery semantics. SUCCESS may be SMTP acceptance; DELIVERED is a stored delivery report, not inbox placement or reading. No provider polling, raw diagnostics, template HTML, secrets or SMTP fields are exposed. No query parameter or HTTP body is accepted.

### Authentication

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Required permissions

```json
{
  "accepted": "messages:read",
  "additional": [
    "contacts:read"
  ]
}
```

### Parameters

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "description": "UUID of the organisation-owned message campaign.",
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

```json
{
  "name": "commandId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### Responses

#### HTTP 200

```json
{
  "description": "Recorded individual email observation, with qualified receipt evidence and current identity admission.",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/CampaignTemplateDeliveryResponse"
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "Invalid UUID or envelope, unknown query/body field, malformed revision or idempotency key.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "Missing or invalid API key.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "Required campaign capabilities are missing.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "Campaign or command unavailable in the authenticated organisation.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "Revision/idempotency conflict or unsupported/ambiguous stored campaign history. Read current state; do not resend.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "The request could not complete. Read the existing command and campaign before another action.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "COMMAND_JOURNAL_UNAVAILABLE: outcome may require reading the same command; no new send or duplication is authorised.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "error"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "messages:read",
  "x-unisoft-mcp-output-schema": true,
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  },
  "x-unisoft-additional-scopes": [
    "contacts:read"
  ]
}
```

## Schemas

```json
{
  "components": {
    "schemas": {
      "Campaign": {
        "type": "object",
        "description": "A message campaign (collection messages): a WhatsApp/SMS/Email broadcast. Lifecycle state INIT (draft) → VALIDATE (sent) → FINISHED. `targets`/`percentSuccess`/`percentError` are computed from the deliveries.",
        "properties": {
          "crmTarget": {
            "type": "object",
            "readOnly": true,
            "description": "Versioned contact-list/category targeting. Union by default; exclusions override inclusion. Backoffice review required before editing, preview or send."
          },
          "id": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "enum": [
              "WHATSAPP",
              "SMS",
              "EMAIL",
              "WHATSAPP_OU_SMS",
              "WHATSAPP_OU_EMAIL",
              "WHATSAPP_OU_SMS_OU_EMAIL",
              "SMS_OU_EMAIL"
            ],
            "description": "Channel or fallback cascade."
          },
          "state": {
            "type": "string",
            "enum": [
              "INIT",
              "VALIDATE",
              "FINISHED"
            ],
            "readOnly": true,
            "description": "INIT = draft (editable); VALIDATE = sending/sent; FINISHED = done."
          },
          "subject": {
            "type": "string",
            "description": "Email subject (EMAIL channels)."
          },
          "message": {
            "type": "string",
            "description": "Message body (text, with {{firstname}}/{{lastname}}/{{hebrewname}} templating; legacy {{prenom}}/{{nom}}/{{prenomHE}} aliases remain supported)."
          },
          "emailContent": {
            "type": "string",
            "description": "Full HTML email body (alternative to emailTemplate)."
          },
          "emailTemplate": {
            "type": "string",
            "nullable": true,
            "description": "id of an email template (its HTML is loaded into emailContent at send time)."
          },
          "emailConfig": {
            "type": "string",
            "nullable": true,
            "description": "id of the email sending config to use (see GET /messaging-configs)."
          },
          "smsConfig": {
            "type": "string",
            "nullable": true,
            "description": "id of an SMS config — accepted for parity but IGNORED by the SMS daemon (mono-config per org)."
          },
          "whatsappAccountId": {
            "type": "string",
            "nullable": true,
            "description": "Sending WhatsApp number id (required when type contains WHATSAPP)."
          },
          "allContact": {
            "type": "boolean",
            "description": "Targeting: all contacts."
          },
          "staredOnly": {
            "type": "boolean",
            "description": "Targeting: local/starred contacts (Proximité module)."
          },
          "categories": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Targeting: contacts in any of these categories."
          },
          "excludedCategories": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 400
            },
            "description": "Exclude contacts in ANY named category from all/local/category targeting. Exclusions apply before resolving children and again to parent recipients. Exact category names; no contacts are deleted. Not supported for imports, forms, anonymous push or crmTarget (use crmTarget.excludedCategories there)."
          },
          "familles": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Legacy field, stored but NOT used for targeting."
          },
          "docs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CampaignMedia"
            }
          },
          "videos": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CampaignMedia"
            }
          },
          "links": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CampaignLink"
            }
          },
          "prefix": {
            "type": "string"
          },
          "scheduledAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Send time (null = immediate after send)."
          },
          "datetime": {
            "type": "string",
            "format": "date-time",
            "readOnly": true
          },
          "targets": {
            "type": "integer",
            "readOnly": true,
            "description": "Number of deliveries (after send)."
          },
          "percentSuccess": {
            "type": "string",
            "readOnly": true
          },
          "percentError": {
            "type": "string",
            "readOnly": true
          }
        }
      },
      "CampaignMedia": {
        "type": "object",
        "description": "A campaign media item. `doc` is an http(s) URL (re-hosted on write) or a filename already hosted (e.g. returned by POST /uploads).",
        "properties": {
          "name": {
            "type": "string",
            "description": "Display label."
          },
          "doc": {
            "type": "string",
            "description": "http(s) URL (re-hosted) or hosted filename."
          }
        }
      },
      "CampaignLink": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "Pagination": {
        "type": "object",
        "properties": {
          "nextCursor": {
            "type": "string",
            "nullable": true
          },
          "hasMore": {
            "type": "boolean"
          },
          "count": {
            "type": "integer"
          }
        }
      },
      "UnisoftRequest_a64ca28f296f1c41c444": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "WHATSAPP",
              "SMS",
              "EMAIL",
              "WHATSAPP_OU_SMS",
              "WHATSAPP_OU_EMAIL",
              "WHATSAPP_OU_SMS_OU_EMAIL",
              "SMS_OU_EMAIL"
            ],
            "description": "Required on create."
          },
          "whatsappAccountId": {
            "type": "string",
            "description": "Required when type contains WHATSAPP."
          },
          "subject": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "emailContent": {
            "type": "string"
          },
          "emailTemplate": {
            "type": "string",
            "description": "id of an existing email template."
          },
          "emailConfig": {
            "type": "string",
            "description": "id of an existing email config (GET /messaging-configs)."
          },
          "smsConfig": {
            "type": "string",
            "description": "id of an SMS config (accepted but ignored by the daemon)."
          },
          "allContact": {
            "type": "boolean"
          },
          "staredOnly": {
            "type": "boolean"
          },
          "categories": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "excludedCategories": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 400
            },
            "description": "Optional category exclusions for allContact, staredOnly or categories audiences. A match in any category excludes the source contact and final parent recipient. Exact category names, case-sensitive. Omit on update to preserve; [] clears. For crmTarget use its own excludedCategories via the audience command. Does not send or delete contacts."
          },
          "familles": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "docs": {
            "type": "array",
            "maxItems": 20,
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string",
                  "description": "Display label."
                },
                "doc": {
                  "type": "string",
                  "description": "http(s) URL (re-hosted) or hosted filename."
                }
              },
              "additionalProperties": false,
              "description": "A campaign media item. `doc` is an http(s) URL (re-hosted on write) or a filename already hosted (e.g. returned by POST /uploads)."
            }
          },
          "videos": {
            "type": "array",
            "maxItems": 20,
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string",
                  "description": "Display label."
                },
                "doc": {
                  "type": "string",
                  "description": "http(s) URL (re-hosted) or hosted filename."
                }
              },
              "additionalProperties": false,
              "description": "A campaign media item. `doc` is an http(s) URL (re-hosted on write) or a filename already hosted (e.g. returned by POST /uploads)."
            }
          },
          "links": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "url": {
                  "type": "string",
                  "format": "uri"
                }
              },
              "additionalProperties": false
            }
          },
          "prefix": {
            "type": "string"
          },
          "scheduledAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        },
        "required": [
          "type"
        ],
        "additionalProperties": false,
        "description": "Contact-list campaigns expose crmTarget for reading; editing, target preview and send require backoffice review (CONTACT_LIST_REVIEW_REQUIRED). New crmTarget writes are rejected by this API. Create or update a message campaign. Targeting is MUTUALLY EXCLUSIVE: set exactly one of `allContact`, `staredOnly` or `categories`.\nWhen `type` contains WHATSAPP, `whatsappAccountId` is REQUIRED and must be a connected number (see GET /whatsapp-accounts).\nMedia (`docs`/`videos`): each item's `doc` may be an http(s) URL (re-hosted) or a filename returned by POST /uploads.\nA campaign is created in state INIT (draft); editing is only allowed while INIT. Sending is a separate action (POST /{id}/send, scope messages:send)."
      },
      "UnisoftRequest_eb7a1a258ea96fc9aa42": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "WHATSAPP",
              "SMS",
              "EMAIL",
              "WHATSAPP_OU_SMS",
              "WHATSAPP_OU_EMAIL",
              "WHATSAPP_OU_SMS_OU_EMAIL",
              "SMS_OU_EMAIL"
            ],
            "description": "Required on create."
          },
          "whatsappAccountId": {
            "type": "string",
            "description": "Required when type contains WHATSAPP."
          },
          "subject": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "emailContent": {
            "type": "string"
          },
          "emailTemplate": {
            "type": "string",
            "description": "id of an existing email template."
          },
          "emailConfig": {
            "type": "string",
            "description": "id of an existing email config (GET /messaging-configs)."
          },
          "smsConfig": {
            "type": "string",
            "description": "id of an SMS config (accepted but ignored by the daemon)."
          },
          "allContact": {
            "type": "boolean"
          },
          "staredOnly": {
            "type": "boolean"
          },
          "categories": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "excludedCategories": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 400
            },
            "description": "Optional category exclusions for allContact, staredOnly or categories audiences. A match in any category excludes the source contact and final parent recipient. Exact category names, case-sensitive. Omit on update to preserve; [] clears. For crmTarget use its own excludedCategories via the audience command. Does not send or delete contacts."
          },
          "familles": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "docs": {
            "type": "array",
            "maxItems": 20,
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string",
                  "description": "Display label."
                },
                "doc": {
                  "type": "string",
                  "description": "http(s) URL (re-hosted) or hosted filename."
                }
              },
              "additionalProperties": false,
              "description": "A campaign media item. `doc` is an http(s) URL (re-hosted on write) or a filename already hosted (e.g. returned by POST /uploads)."
            }
          },
          "videos": {
            "type": "array",
            "maxItems": 20,
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string",
                  "description": "Display label."
                },
                "doc": {
                  "type": "string",
                  "description": "http(s) URL (re-hosted) or hosted filename."
                }
              },
              "additionalProperties": false,
              "description": "A campaign media item. `doc` is an http(s) URL (re-hosted on write) or a filename already hosted (e.g. returned by POST /uploads)."
            }
          },
          "links": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "url": {
                  "type": "string",
                  "format": "uri"
                }
              },
              "additionalProperties": false
            }
          },
          "prefix": {
            "type": "string"
          },
          "scheduledAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "Contact-list campaigns expose crmTarget for reading; editing, target preview and send require backoffice review (CONTACT_LIST_REVIEW_REQUIRED). New crmTarget writes are rejected by this API. Create or update a message campaign. Targeting is MUTUALLY EXCLUSIVE: set exactly one of `allContact`, `staredOnly` or `categories`.\nWhen `type` contains WHATSAPP, `whatsappAccountId` is REQUIRED and must be a connected number (see GET /whatsapp-accounts).\nMedia (`docs`/`videos`): each item's `doc` may be an http(s) URL (re-hosted) or a filename returned by POST /uploads.\nA campaign is created in state INIT (draft); editing is only allowed while INIT. Sending is a separate action (POST /{id}/send, scope messages:send)."
      },
      "CampaignTargets": {
        "type": "object",
        "properties": {
          "total": {
            "type": "integer",
            "description": "Number of recipients the targeting resolves to."
          }
        }
      },
      "CampaignReschedulingPreview": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "campaignId",
          "expectedRevision",
          "previousScheduledAt",
          "scheduledAt",
          "targetCount",
          "excludedTestCount",
          "channels",
          "minimumFutureSeconds",
          "audienceChanged",
          "contentChanged",
          "source",
          "providerChecked"
        ],
        "properties": {
          "campaignId": {
            "type": "string",
            "format": "uuid"
          },
          "expectedRevision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "previousScheduledAt": {
            "type": "string",
            "format": "date-time"
          },
          "scheduledAt": {
            "type": "string",
            "format": "date-time"
          },
          "targetCount": {
            "type": "integer",
            "minimum": 1,
            "maximum": 2000
          },
          "excludedTestCount": {
            "type": "integer",
            "minimum": 0
          },
          "channels": {
            "type": "array",
            "maxItems": 3,
            "items": {
              "type": "string",
              "enum": [
                "EMAIL",
                "SMS",
                "WHATSAPP"
              ]
            }
          },
          "minimumFutureSeconds": {
            "type": "integer",
            "enum": [
              60
            ]
          },
          "audienceChanged": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "contentChanged": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "source": {
            "type": "string",
            "enum": [
              "NATIVE_MATERIALIZED_SEND_QUEUE"
            ]
          },
          "providerChecked": {
            "type": "boolean",
            "enum": [
              false
            ]
          }
        }
      },
      "CampaignReschedulingCommand": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "commandId",
          "campaignId",
          "state",
          "scheduledAt",
          "previousScheduledAt",
          "targetCount",
          "changedDeliveryCount",
          "reason",
          "startedAt",
          "finishedAt",
          "fenceReleased",
          "audienceChanged",
          "contentChanged",
          "providerChecked"
        ],
        "properties": {
          "commandId": {
            "type": "string",
            "format": "uuid"
          },
          "campaignId": {
            "type": "string",
            "format": "uuid"
          },
          "state": {
            "type": "string",
            "enum": [
              "PENDING",
              "RUNNING",
              "SCHEDULED",
              "REJECTED",
              "UNKNOWN"
            ]
          },
          "scheduledAt": {
            "type": "string",
            "format": "date-time"
          },
          "previousScheduledAt": {
            "type": "string",
            "format": "date-time"
          },
          "targetCount": {
            "type": "integer",
            "minimum": 1,
            "maximum": 2000
          },
          "changedDeliveryCount": {
            "type": "integer",
            "minimum": 1,
            "maximum": 2000,
            "nullable": true
          },
          "reason": {
            "type": "string",
            "nullable": true
          },
          "startedAt": {
            "type": "string",
            "format": "date-time"
          },
          "finishedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "fenceReleased": {
            "type": "boolean"
          },
          "audienceChanged": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "contentChanged": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "providerChecked": {
            "type": "boolean",
            "enum": [
              false
            ]
          }
        }
      },
      "CampaignAudienceDispatchPreviewResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/CampaignAudienceDispatchPreview"
          }
        }
      },
      "CampaignAudienceDispatchPreview": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "campaignId",
          "expectedRevision",
          "audienceHash",
          "preparedRecordCount",
          "selectedContactCount",
          "channels",
          "scheduledAt",
          "maxRecords",
          "maxQueueBytes",
          "queueCreated",
          "providerChecked",
          "readAt"
        ],
        "properties": {
          "campaignId": {
            "type": "string",
            "format": "uuid"
          },
          "expectedRevision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "audienceHash": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "preparedRecordCount": {
            "type": "integer",
            "minimum": 1,
            "maximum": 2000
          },
          "selectedContactCount": {
            "type": "integer",
            "minimum": 0,
            "maximum": 20000
          },
          "channels": {
            "type": "array",
            "minItems": 3,
            "maxItems": 3,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "channel",
                "recordCount"
              ],
              "properties": {
                "channel": {
                  "type": "string",
                  "enum": [
                    "EMAIL",
                    "SMS",
                    "WHATSAPP"
                  ]
                },
                "recordCount": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 2000
                }
              }
            }
          },
          "scheduledAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "maxRecords": {
            "type": "integer",
            "enum": [
              2000
            ]
          },
          "maxQueueBytes": {
            "type": "integer",
            "enum": [
              16777216
            ]
          },
          "queueCreated": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "providerChecked": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "readAt": {
            "type": "string",
            "format": "date-time"
          },
          "sms": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "estimateHash",
              "catalogueVersion",
              "records",
              "unisoftUnits",
              "externalRecords",
              "unavailableRecords",
              "availableUnits",
              "remainingUnits"
            ],
            "properties": {
              "estimateHash": {
                "type": "string",
                "pattern": "^[a-f0-9]{64}$"
              },
              "catalogueVersion": {
                "type": "string",
                "nullable": true
              },
              "records": {
                "type": "integer",
                "minimum": 0,
                "maximum": 2000
              },
              "unisoftUnits": {
                "type": "integer",
                "minimum": 0,
                "maximum": 9007199254740991
              },
              "externalRecords": {
                "type": "integer",
                "minimum": 0,
                "maximum": 2000
              },
              "unavailableRecords": {
                "type": "integer",
                "minimum": 0,
                "maximum": 2000
              },
              "availableUnits": {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991,
                "nullable": true
              },
              "remainingUnits": {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991,
                "nullable": true
              }
            }
          }
        }
      },
      "CampaignAudienceDispatchCommandResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/CampaignAudienceDispatchCommand"
          }
        }
      },
      "CampaignAudienceDispatchCommand": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "commandId",
          "campaignId",
          "status",
          "preparedRecordCount",
          "queuedRecordCount",
          "queueAdmission",
          "campaignReserved",
          "reservationStatus",
          "journalState",
          "retryable",
          "errorCode",
          "startedAt",
          "finishedAt",
          "stopCleanup",
          "queueObservation",
          "observedDeliveryCount",
          "providerChecked",
          "canRecallHandedOff"
        ],
        "properties": {
          "commandId": {
            "type": "string",
            "format": "uuid"
          },
          "campaignId": {
            "type": "string",
            "format": "uuid"
          },
          "status": {
            "type": "string",
            "enum": [
              "PENDING",
              "QUEUED",
              "COMPLETED",
              "REJECTED",
              "UNCERTAIN"
            ]
          },
          "preparedRecordCount": {
            "type": "integer",
            "minimum": 0,
            "maximum": 2000,
            "nullable": true
          },
          "queuedRecordCount": {
            "type": "integer",
            "minimum": 0,
            "maximum": 2000,
            "nullable": true
          },
          "queueAdmission": {
            "type": "string",
            "enum": [
              "NOT_STARTED",
              "CONFIRMED",
              "UNKNOWN"
            ]
          },
          "campaignReserved": {
            "type": "boolean",
            "nullable": true
          },
          "reservationStatus": {
            "type": "string",
            "enum": [
              "HELD",
              "RELEASED",
              "STOP_REQUESTED",
              "UNKNOWN"
            ]
          },
          "journalState": {
            "type": "string",
            "enum": [
              "RECORDED",
              "UNCONFIRMED"
            ]
          },
          "retryable": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "errorCode": {
            "type": "string",
            "nullable": true,
            "enum": [
              "CAMPAIGN_CHANGED",
              "SAVED_AUDIENCE_CHANGED",
              "CAMPAIGN_ALREADY_HAS_DELIVERIES",
              "CAMPAIGN_STOP_REQUESTED",
              "CAMPAIGN_OPERATION_BUSY",
              "CAMPAIGN_FENCE_UNCERTAIN",
              "CAMPAIGN_FENCE_LOST",
              "DISPATCH_RESULT_UNKNOWN",
              "DISPATCH_SOURCE_UNAVAILABLE",
              "DISPATCH_SENDER_UNAVAILABLE",
              "DISPATCH_MEDIA_UNAVAILABLE",
              "DISPATCH_LIMIT_REACHED",
              "SMS_ESTIMATE_CHANGED",
              "SMS_QUOTA_INSUFFICIENT",
              null
            ]
          },
          "startedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "finishedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "stopCleanup": {
            "type": "string",
            "enum": [
              "NOT_OBSERVED",
              "NOT_NEEDED",
              "CANCELED_PENDING",
              "UNCONFIRMED"
            ]
          },
          "queueObservation": {
            "type": "string",
            "enum": [
              "COMPLETE",
              "PARTIAL",
              "UNAVAILABLE"
            ]
          },
          "observedDeliveryCount": {
            "type": "integer",
            "minimum": 0,
            "maximum": 2000,
            "nullable": true
          },
          "providerChecked": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "canRecallHandedOff": {
            "type": "boolean",
            "enum": [
              false
            ]
          }
        }
      },
      "CampaignDeliveryProgressResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/CampaignDeliveryProgress"
          }
        }
      },
      "CampaignDeliveryProgress": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "campaignId",
          "state",
          "configuredChannel",
          "initialTargetCount",
          "scheduledAt",
          "dispatchStopped",
          "totals",
          "channels",
          "unclassifiedTestRecordCount",
          "source"
        ],
        "properties": {
          "campaignId": {
            "type": "string",
            "format": "uuid"
          },
          "state": {
            "type": "string",
            "nullable": true,
            "enum": [
              "INIT",
              "VALIDATE",
              "FINISHED",
              null
            ],
            "description": "Stored campaign lifecycle. FINISHED can follow an emergency stop and proves neither queue completeness nor delivery. Unsupported history is null."
          },
          "configuredChannel": {
            "type": "string",
            "nullable": true,
            "enum": [
              "EMAIL",
              "SMS",
              "WHATSAPP",
              "WHATSAPP_OU_SMS",
              "WHATSAPP_OU_EMAIL",
              "WHATSAPP_OU_SMS_OU_EMAIL",
              "SMS_OU_EMAIL",
              "APPMOBILE_NOTIFICATION",
              null
            ]
          },
          "initialTargetCount": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "nullable": true,
            "description": "Stored messages.targets when a valid nonnegative safe integer, otherwise null. An initial dispatch count, not a freshly resolved audience or a per-channel forecast. Fallback rows can make recordCount larger."
          },
          "scheduledAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Stored campaign BSON date as ISO instant; null when missing or invalid. Per-row schedules determine queue classification."
          },
          "dispatchStopped": {
            "type": "boolean",
            "nullable": true,
            "description": "Explicit stored stop marker; null when absent or malformed. This read performs no stop or cancellation."
          },
          "totals": {
            "$ref": "#/components/schemas/CampaignDeliveryProgressCounts"
          },
          "channels": {
            "type": "array",
            "maxItems": 6,
            "items": {
              "$ref": "#/components/schemas/CampaignDeliveryProgressChannel"
            }
          },
          "unclassifiedTestRecordCount": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Rows with a malformed test flag. Excluded from all non-test totals and channel counts because their test status is unknown; explicit true tests are excluded entirely."
          },
          "source": {
            "$ref": "#/components/schemas/CampaignDeliveryProgressSource"
          }
        }
      },
      "CampaignDeliveryProgressCounts": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "recordCount",
          "pendingCount",
          "scheduledPendingCount",
          "readyOrInFlightCount",
          "unknownSchedulePendingCount",
          "successCount",
          "failureCount",
          "canceledCount",
          "unknownStateCount",
          "deliveryUncertainCount",
          "simulationCount",
          "inProgressCount"
        ],
        "properties": {
          "recordCount": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Stored non-test delivery rows in this bucket, including fallback rows. Not unique recipients, intended audience size or confirmed deliveries."
          },
          "pendingCount": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Stored INIT rows; includes scheduled work, ready work and potentially an active provider call."
          },
          "scheduledPendingCount": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "INIT rows with a BSON date scheduledAt strictly after source.observedAt. This is scheduled queue work, not a forecast audience."
          },
          "readyOrInFlightCount": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "INIT rows with no scheduledAt, null scheduledAt, or a BSON date at or before source.observedAt. Waiting and in-flight provider work cannot be separated."
          },
          "unknownSchedulePendingCount": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "INIT rows whose stored schedule has an unsupported type. They are not silently assumed ready or scheduled."
          },
          "successCount": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Rows recorded SUCCESS. Email SUCCESS can mean SMTP acceptance only; no inbox delivery, read receipt or provider status check is established."
          },
          "failureCount": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Rows recorded ERROR, including explicitly uncertain outcomes. This does not authorise retry or establish that a provider received nothing."
          },
          "canceledCount": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Rows recorded CANCELED or CANCELLED, including simulation cancellations. Already handed-off messages cannot be recalled."
          },
          "unknownStateCount": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Rows with a missing, malformed or unsupported stored state. No raw historical value is exposed or coerced to success."
          },
          "deliveryUncertainCount": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Overlay count of deliveryUncertain:true or exact MAILER_DELIVERY_UNCERTAIN records. Other rows are not thereby proven certain; never add this overlay to state counts."
          },
          "simulationCount": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Overlay count of simulation:true records, not real successful deliveries. Never add this overlay to state counts."
          },
          "inProgressCount": {
            "type": "integer",
            "nullable": true,
            "enum": [
              null
            ],
            "description": "Always null: workers have no common reliable persisted in-flight state. Never present null as zero."
          }
        }
      },
      "CampaignDeliveryProgressChannel": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "channel",
          "recordCount",
          "pendingCount",
          "scheduledPendingCount",
          "readyOrInFlightCount",
          "unknownSchedulePendingCount",
          "successCount",
          "failureCount",
          "canceledCount",
          "unknownStateCount",
          "deliveryUncertainCount",
          "simulationCount",
          "inProgressCount"
        ],
        "properties": {
          "channel": {
            "type": "string",
            "enum": [
              "EMAIL",
              "SMS",
              "WHATSAPP",
              "NOTIFICATION",
              "APPMOBILE_NOTIFICATION",
              "UNKNOWN"
            ],
            "description": "Exact recorded channel when supported; UNKNOWN combines missing, malformed and unsupported channels without exposing raw values."
          },
          "recordCount": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Stored non-test delivery rows in this bucket, including fallback rows. Not unique recipients, intended audience size or confirmed deliveries."
          },
          "pendingCount": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Stored INIT rows; includes scheduled work, ready work and potentially an active provider call."
          },
          "scheduledPendingCount": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "INIT rows with a BSON date scheduledAt strictly after source.observedAt. This is scheduled queue work, not a forecast audience."
          },
          "readyOrInFlightCount": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "INIT rows with no scheduledAt, null scheduledAt, or a BSON date at or before source.observedAt. Waiting and in-flight provider work cannot be separated."
          },
          "unknownSchedulePendingCount": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "INIT rows whose stored schedule has an unsupported type. They are not silently assumed ready or scheduled."
          },
          "successCount": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Rows recorded SUCCESS. Email SUCCESS can mean SMTP acceptance only; no inbox delivery, read receipt or provider status check is established."
          },
          "failureCount": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Rows recorded ERROR, including explicitly uncertain outcomes. This does not authorise retry or establish that a provider received nothing."
          },
          "canceledCount": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Rows recorded CANCELED or CANCELLED, including simulation cancellations. Already handed-off messages cannot be recalled."
          },
          "unknownStateCount": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Rows with a missing, malformed or unsupported stored state. No raw historical value is exposed or coerced to success."
          },
          "deliveryUncertainCount": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Overlay count of deliveryUncertain:true or exact MAILER_DELIVERY_UNCERTAIN records. Other rows are not thereby proven certain; never add this overlay to state counts."
          },
          "simulationCount": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Overlay count of simulation:true records, not real successful deliveries. Never add this overlay to state counts."
          },
          "inProgressCount": {
            "type": "integer",
            "nullable": true,
            "enum": [
              null
            ],
            "description": "Always null: workers have no common reliable persisted in-flight state. Never present null as zero."
          }
        }
      },
      "CampaignDeliveryProgressSource": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "collection",
          "scope",
          "observedAt",
          "readAt",
          "computedAt",
          "inProgressAvailability",
          "audienceResolved",
          "queueCompleteness",
          "providerChecked"
        ],
        "properties": {
          "collection": {
            "type": "string",
            "enum": [
              "send"
            ]
          },
          "scope": {
            "type": "string",
            "enum": [
              "STORED_CAMPAIGN_DELIVERY_RECORDS"
            ]
          },
          "observedAt": {
            "type": "string",
            "format": "date-time",
            "description": "Start of the queue observation and fixed instant used to classify scheduled INIT rows."
          },
          "readAt": {
            "type": "string",
            "format": "date-time",
            "description": "End of this database read; concurrent writes may occur. Not a provider verification or immutable snapshot timestamp."
          },
          "computedAt": {
            "type": "string",
            "nullable": true,
            "enum": [
              null
            ]
          },
          "inProgressAvailability": {
            "type": "string",
            "enum": [
              "UNAVAILABLE_NO_COMMON_PERSISTED_IN_FLIGHT_STATE"
            ]
          },
          "audienceResolved": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "queueCompleteness": {
            "type": "string",
            "enum": [
              "UNKNOWN"
            ]
          },
          "providerChecked": {
            "type": "boolean",
            "enum": [
              false
            ]
          }
        }
      },
      "CampaignDeliveryListResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data",
          "meta",
          "source"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "type": "array",
            "maxItems": 200,
            "items": {
              "$ref": "#/components/schemas/CampaignDeliveryRecord"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/CampaignDeliveryListMeta"
          },
          "source": {
            "$ref": "#/components/schemas/CampaignDeliveryListSource"
          }
        }
      },
      "CampaignDeliveryRecord": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "deliveryId",
          "channel",
          "state",
          "recipient",
          "createdAt",
          "attemptedAt",
          "scheduledAt",
          "canceledAt",
          "smtpAcceptedAt",
          "deliveredReportAt",
          "deliveryUpdatedAt",
          "deliveryStatus",
          "whatsappAck",
          "whatsappAckAt",
          "reasonCode",
          "reasonAvailability",
          "deliveryUncertain",
          "simulation"
        ],
        "properties": {
          "deliveryId": {
            "type": "string",
            "format": "uuid"
          },
          "channel": {
            "type": "string",
            "enum": [
              "EMAIL",
              "SMS",
              "WHATSAPP",
              "NOTIFICATION",
              "APPMOBILE_NOTIFICATION",
              "UNKNOWN"
            ]
          },
          "state": {
            "type": "string",
            "enum": [
              "INIT",
              "SUCCESS",
              "ERROR",
              "CANCELED",
              "UNKNOWN"
            ]
          },
          "recipient": {
            "$ref": "#/components/schemas/CampaignDeliveryRecipient"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "attemptedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "scheduledAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "canceledAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "smtpAcceptedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "deliveredReportAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "deliveryUpdatedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "deliveryStatus": {
            "type": "string",
            "nullable": true,
            "enum": [
              "ACCEPTED",
              "DELIVERED",
              "RELAYED",
              "EXPANDED",
              "DELAYED",
              "ERROR",
              "UNKNOWN",
              null
            ],
            "description": "Recorded email status only, without provider polling. ACCEPTED is SMTP acceptance; DELIVERED is a stored positive delivery report, not proof of inbox placement or reading. null means absent, malformed or not an email row."
          },
          "whatsappAck": {
            "type": "integer",
            "minimum": 0,
            "maximum": 4,
            "nullable": true,
            "description": "Stored WhatsApp acknowledgement only: the current consumer interprets 1 as sent, 2 as received and 3 or greater as read. No new receipt is fetched; null means unavailable or unsupported."
          },
          "whatsappAckAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "reasonCode": {
            "type": "string",
            "nullable": true,
            "enum": [
              "API_PHONE_BAD_COUNTRY",
              "API_PHONE_BAD_FORMAT",
              "API_EMAIL_BAD_FORMAT",
              "API_EMAIL_UNSUBSCRIBE",
              "MAILER_BAD_CONFIG",
              "MAILER_INVALID_RETRY",
              "MAILER_MAX_ATTEMPTS",
              "MAILER_INVALID_ID",
              "MAILER_DELIVERY_UNCERTAIN",
              "DELIVERY_REPORT_FAILED",
              "USER_EMERGENCY_STOP",
              "SMS_TEST_MODE",
              "SMS_CONFIGURATION_ERROR",
              "INVALID_PHONE_NUMBER",
              "SMS_NOT_AVAILABLE",
              "EMPTY_MESSAGE",
              "SMS_QUOTA_EXCEEDED",
              "WHATSAPP_SEND_ERROR",
              "INVALID_WHATSAPP_NUMBER",
              "WHATSAPP_NUMBER_BLOCKED",
              "WHATSAPP_ACCOUNT_NOT_READY",
              "WHATSAPP_NO_ACCOUNT",
              "WHATSAPP_MEDIA_FAILED",
              "WHATSAPP_TEXT_FAILED",
              null
            ],
            "description": "Allowlisted stored errorCode or stopReason only. null means no known safe reason is available, not no failure. Raw provider diagnostics, SMTP responses and errorMessage are never exposed."
          },
          "reasonAvailability": {
            "type": "string",
            "enum": [
              "KNOWN_CODE",
              "UNAVAILABLE"
            ]
          },
          "deliveryUncertain": {
            "type": "boolean",
            "nullable": true,
            "enum": [
              true,
              null
            ],
            "description": "true when an explicit uncertainty marker or MAILER_DELIVERY_UNCERTAIN is recorded. Otherwise null; absence does not establish non-delivery or safe retry."
          },
          "simulation": {
            "type": "boolean",
            "nullable": true
          }
        }
      },
      "CampaignDeliveryRecipient": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "contactId",
          "identityStatus",
          "firstName",
          "lastName",
          "email",
          "phone"
        ],
        "properties": {
          "contactId": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "identityStatus": {
            "type": "string",
            "enum": [
              "CURRENT_CONTACT_REFERENCE",
              "SNAPSHOT_ONLY",
              "UNAVAILABLE"
            ],
            "description": "CURRENT_CONTACT_REFERENCE means the stored contact UUID was re-admitted in the current organisation. SNAPSHOT_ONLY means no contact reference was stored. UNAVAILABLE masks identity when a stored reference is invalid, deleted or foreign. Names and destinations are historical send snapshots, never refreshed contact data."
          },
          "firstName": {
            "type": "string",
            "nullable": true,
            "maxLength": 200
          },
          "lastName": {
            "type": "string",
            "nullable": true,
            "maxLength": 200
          },
          "email": {
            "type": "string",
            "nullable": true,
            "maxLength": 320
          },
          "phone": {
            "type": "string",
            "nullable": true,
            "maxLength": 32
          }
        }
      },
      "CampaignDeliveryListMeta": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "nextCursor",
          "hasMore",
          "count"
        ],
        "properties": {
          "nextCursor": {
            "type": "string",
            "nullable": true
          },
          "hasMore": {
            "type": "boolean"
          },
          "count": {
            "type": "integer",
            "minimum": 0,
            "maximum": 200
          }
        }
      },
      "CampaignDeliveryListSource": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "readAt",
          "providerChecked",
          "scope",
          "maxRecords"
        ],
        "properties": {
          "readAt": {
            "type": "string",
            "format": "date-time"
          },
          "providerChecked": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "scope": {
            "type": "string",
            "enum": [
              "STORED_NON_TEST_DELIVERY_RECORDS"
            ]
          },
          "maxRecords": {
            "type": "integer",
            "enum": [
              10000
            ]
          }
        }
      },
      "CampaignDeliveryRecordResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data",
          "source"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/CampaignDeliveryRecord"
          },
          "source": {
            "$ref": "#/components/schemas/CampaignDeliveryRecordSource"
          }
        }
      },
      "CampaignDeliveryRecordSource": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "readAt",
          "providerChecked"
        ],
        "properties": {
          "readAt": {
            "type": "string",
            "format": "date-time"
          },
          "providerChecked": {
            "type": "boolean",
            "enum": [
              false
            ]
          }
        }
      },
      "CampaignStopPreviewResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/CampaignStopPreview"
          }
        }
      },
      "CampaignStopPreview": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "campaignId",
          "revision",
          "state",
          "stopRecorded",
          "pendingRecordCount",
          "observedAt",
          "includesTests",
          "activeProviderCalls",
          "canRecallHandedOff",
          "rescheduleAvailable",
          "reschedulePrerequisite"
        ],
        "properties": {
          "campaignId": {
            "type": "string",
            "format": "uuid"
          },
          "revision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "state": {
            "type": "string",
            "enum": [
              "INIT",
              "VALIDATE",
              "FINISHED"
            ]
          },
          "stopRecorded": {
            "type": "boolean"
          },
          "pendingRecordCount": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          },
          "observedAt": {
            "type": "string",
            "format": "date-time"
          },
          "includesTests": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "activeProviderCalls": {
            "type": "string",
            "enum": [
              "UNKNOWN"
            ]
          },
          "canRecallHandedOff": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "rescheduleAvailable": {
            "type": "boolean",
            "nullable": true,
            "enum": [
              null
            ]
          },
          "reschedulePrerequisite": {
            "type": "string",
            "enum": [
              "USE_DEDICATED_RESCHEDULING_PREVIEW"
            ]
          }
        }
      },
      "CampaignDeliveryCommandResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/CampaignDeliveryCommand"
          }
        }
      },
      "CampaignDeliveryCommand": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "commandId",
          "campaignId",
          "action",
          "state",
          "stopRecorded",
          "canceledRecordCount",
          "remainingPendingRecordCount",
          "errorCode",
          "startedAt",
          "finishedAt",
          "deliveryId",
          "selectionSaved",
          "audienceCount",
          "audienceHash",
          "canRecallHandedOff",
          "providerChecked"
        ],
        "properties": {
          "commandId": {
            "type": "string",
            "format": "uuid"
          },
          "campaignId": {
            "type": "string",
            "format": "uuid"
          },
          "action": {
            "type": "string",
            "enum": [
              "STOP",
              "UPDATE_AUDIENCE",
              "SEND_TEMPLATE"
            ]
          },
          "state": {
            "type": "string",
            "enum": [
              "ADMITTING",
              "RUNNING",
              "COMPLETED",
              "PARTIAL",
              "REJECTED",
              "UNKNOWN",
              "QUEUED"
            ]
          },
          "stopRecorded": {
            "type": "boolean",
            "nullable": true
          },
          "canceledRecordCount": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "nullable": true
          },
          "remainingPendingRecordCount": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "nullable": true
          },
          "errorCode": {
            "type": "string",
            "nullable": true,
            "enum": [
              "REVISION_CONFLICT",
              "CAMPAIGN_STATE_UNSUPPORTED",
              "CAMPAIGN_HISTORY_REVIEW_REQUIRED",
              "CAMPAIGN_NOT_FOUND",
              "COMMAND_OUTCOME_UNKNOWN",
              "COMMAND_ADMISSION_UNAVAILABLE",
              "AUDIENCE_CHANGED",
              "AUDIENCE_EMPTY",
              "AUDIENCE_HISTORY_REVIEW_REQUIRED",
              "CAMPAIGN_NOT_EDITABLE",
              "AUDIENCE_SOURCE_UNAVAILABLE",
              "CONTACT_UNAVAILABLE",
              "RECIPIENT_UNSUBSCRIBED",
              "TEMPLATE_UNAVAILABLE",
              "TEMPLATE_SEND_CHANGED",
              "CAMPAIGN_OPERATION_BUSY",
              "CAMPAIGN_STOP_REQUESTED",
              "CAMPAIGN_FENCE_UNCERTAIN",
              "CAMPAIGN_FENCE_LOST",
              "CAMPAIGN_FENCE_INVALID",
              null
            ]
          },
          "startedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "finishedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "deliveryId": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "selectionSaved": {
            "type": "boolean",
            "nullable": true
          },
          "audienceCount": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "nullable": true
          },
          "audienceHash": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$",
            "nullable": true
          },
          "canRecallHandedOff": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "providerChecked": {
            "type": "boolean",
            "enum": [
              false
            ]
          }
        }
      },
      "UnisoftRequest_46ebc7072c9dc383fded": {
        "type": "object",
        "properties": {
          "version": {
            "type": "integer",
            "enum": [
              1
            ]
          },
          "allContact": {
            "type": "boolean",
            "description": "Set true to start from every non-deleted contact visible to this connection, then apply excludedListIds and excludedCategories. Requires empty listIds/categories and operator union. Omit or false keeps the explicit list/category selection; no implicit all-contact fallback."
          },
          "operator": {
            "type": "string",
            "enum": [
              "union",
              "intersection"
            ],
            "default": "union"
          },
          "listIds": {
            "type": "array",
            "maxItems": 100,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 400
            }
          },
          "categories": {
            "type": "array",
            "maxItems": 100,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 400
            }
          },
          "excludedListIds": {
            "type": "array",
            "maxItems": 100,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 400
            }
          },
          "excludedCategories": {
            "type": "array",
            "maxItems": 100,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 400
            }
          }
        },
        "required": [
          "version"
        ],
        "additionalProperties": false
      },
      "CampaignAudiencePreviewResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/CampaignAudiencePreview"
          }
        }
      },
      "CampaignAudiencePreview": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "campaignId",
          "revision",
          "audienceHash",
          "target",
          "excludedCampaignIds",
          "contactCount",
          "preparedRecordCount",
          "channels",
          "observedAt",
          "queueCreated",
          "sendAuthorised",
          "providerChecked",
          "dispatchRequiresReview"
        ],
        "properties": {
          "campaignId": {
            "type": "string",
            "format": "uuid"
          },
          "revision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "audienceHash": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "target": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "version",
              "operator",
              "listIds",
              "categories",
              "excludedListIds",
              "excludedCategories"
            ],
            "properties": {
              "version": {
                "type": "integer",
                "enum": [
                  1
                ]
              },
              "allContact": {
                "type": "boolean",
                "description": "Set true to start from every non-deleted contact visible to this connection, then apply excludedListIds and excludedCategories. Requires empty listIds/categories and operator union. Omit or false keeps the explicit list/category selection; no implicit all-contact fallback."
              },
              "operator": {
                "type": "string",
                "enum": [
                  "union",
                  "intersection"
                ],
                "default": "union"
              },
              "listIds": {
                "type": "array",
                "maxItems": 100,
                "uniqueItems": true,
                "items": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 400
                }
              },
              "categories": {
                "type": "array",
                "maxItems": 100,
                "uniqueItems": true,
                "items": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 400
                }
              },
              "excludedListIds": {
                "type": "array",
                "maxItems": 100,
                "uniqueItems": true,
                "items": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 400
                }
              },
              "excludedCategories": {
                "type": "array",
                "maxItems": 100,
                "uniqueItems": true,
                "items": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 400
                }
              }
            }
          },
          "excludedCampaignIds": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "type": "string",
              "format": "uuid"
            }
          },
          "contactCount": {
            "type": "integer",
            "minimum": 0,
            "maximum": 20000
          },
          "preparedRecordCount": {
            "type": "integer",
            "minimum": 0,
            "maximum": 20000
          },
          "channels": {
            "type": "array",
            "minItems": 3,
            "maxItems": 3,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "channel",
                "recordCount"
              ],
              "properties": {
                "channel": {
                  "type": "string",
                  "enum": [
                    "EMAIL",
                    "SMS",
                    "WHATSAPP"
                  ]
                },
                "recordCount": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 20000
                }
              }
            }
          },
          "observedAt": {
            "type": "string",
            "format": "date-time"
          },
          "queueCreated": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "sendAuthorised": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "providerChecked": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "dispatchRequiresReview": {
            "type": "boolean",
            "enum": [
              true
            ]
          }
        }
      },
      "CampaignSmsPreviewResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/CampaignSmsPreview"
          }
        }
      },
      "CampaignSmsPreview": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "campaignId",
          "revision",
          "preparedRecordCount",
          "primaryRecordCount",
          "primarySegments",
          "possibleFallbackRecordCount",
          "possibleFallbackSegments",
          "ineligibleSmsRecordCount",
          "groups",
          "quota",
          "pricing",
          "source"
        ],
        "properties": {
          "campaignId": {
            "type": "string",
            "format": "uuid"
          },
          "revision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "preparedRecordCount": {
            "type": "integer",
            "minimum": 0,
            "maximum": 20000
          },
          "primaryRecordCount": {
            "type": "integer",
            "minimum": 0,
            "maximum": 20000
          },
          "primarySegments": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          },
          "possibleFallbackRecordCount": {
            "type": "integer",
            "minimum": 0,
            "maximum": 20000
          },
          "possibleFallbackSegments": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          },
          "ineligibleSmsRecordCount": {
            "type": "integer",
            "minimum": 0,
            "maximum": 20000
          },
          "groups": {
            "type": "array",
            "maxItems": 4,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "route",
                "encoding",
                "recordCount",
                "segments"
              ],
              "properties": {
                "route": {
                  "type": "string",
                  "enum": [
                    "PRIMARY",
                    "POSSIBLE_FALLBACK"
                  ]
                },
                "encoding": {
                  "type": "string",
                  "enum": [
                    "GSM_03_38",
                    "UNICODE"
                  ]
                },
                "recordCount": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 20000
                },
                "segments": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 9007199254740991
                }
              }
            }
          },
          "quota": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "remainingCredits",
              "unit",
              "source",
              "quality",
              "reserved",
              "sufficientForPrimaryEstimate"
            ],
            "properties": {
              "remainingCredits": {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991,
                "nullable": true
              },
              "unit": {
                "type": "string",
                "enum": [
                  "SMS_SEGMENT_CREDIT"
                ]
              },
              "source": {
                "type": "string",
                "enum": [
                  "LEGACY_CRM_GET_NB_SMS_AVAILABLE"
                ]
              },
              "quality": {
                "type": "string",
                "enum": [
                  "OBSERVATION_WITH_KNOWN_LIMITATIONS"
                ]
              },
              "reserved": {
                "type": "boolean",
                "enum": [
                  false
                ]
              },
              "sufficientForPrimaryEstimate": {
                "type": "boolean",
                "nullable": true
              }
            }
          },
          "pricing": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "amountMinor",
              "currency",
              "availability"
            ],
            "properties": {
              "amountMinor": {
                "type": "integer",
                "nullable": true,
                "enum": [
                  null
                ]
              },
              "currency": {
                "type": "string",
                "nullable": true,
                "enum": [
                  null
                ]
              },
              "availability": {
                "type": "string",
                "enum": [
                  "UNAVAILABLE_NO_CANONICAL_TARIFF"
                ]
              }
            }
          },
          "source": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "readAt",
              "providerChecked",
              "queueCreated",
              "audienceReserved",
              "estimateOnly",
              "calculator",
              "providerAppendedContentIncluded"
            ],
            "properties": {
              "readAt": {
                "type": "string",
                "format": "date-time"
              },
              "providerChecked": {
                "type": "boolean",
                "enum": [
                  false
                ]
              },
              "queueCreated": {
                "type": "boolean",
                "enum": [
                  false
                ]
              },
              "audienceReserved": {
                "type": "boolean",
                "enum": [
                  false
                ]
              },
              "estimateOnly": {
                "type": "boolean",
                "enum": [
                  true
                ]
              },
              "calculator": {
                "type": "string",
                "enum": [
                  "NATIVE_GSM_PACKAGE_AND_WORKER_TAG_REMOVAL"
                ]
              },
              "providerAppendedContentIncluded": {
                "type": "boolean",
                "enum": [
                  false
                ]
              }
            }
          },
          "sms": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "estimateHash",
              "catalogueVersion",
              "records",
              "unisoftUnits",
              "externalRecords",
              "unavailableRecords",
              "availableUnits",
              "remainingUnits"
            ],
            "properties": {
              "estimateHash": {
                "type": "string",
                "pattern": "^[a-f0-9]{64}$"
              },
              "catalogueVersion": {
                "type": "string",
                "nullable": true
              },
              "records": {
                "type": "integer",
                "minimum": 0,
                "maximum": 2000
              },
              "unisoftUnits": {
                "type": "integer",
                "minimum": 0,
                "maximum": 9007199254740991
              },
              "externalRecords": {
                "type": "integer",
                "minimum": 0,
                "maximum": 2000
              },
              "unavailableRecords": {
                "type": "integer",
                "minimum": 0,
                "maximum": 2000
              },
              "availableUnits": {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991,
                "nullable": true
              },
              "remainingUnits": {
                "type": "integer",
                "minimum": -9007199254740991,
                "maximum": 9007199254740991,
                "nullable": true
              }
            }
          }
        }
      },
      "CampaignTemplateSendPreviewResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/CampaignTemplateSendPreview"
          }
        }
      },
      "CampaignTemplateSendPreview": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "campaignId",
          "contactId",
          "templateId",
          "recipientEmail",
          "subject",
          "emailConfigId",
          "revision",
          "channel",
          "independentOfBroadcast",
          "campaignStateChanged",
          "queued",
          "providerChecked",
          "templateFrozen",
          "readAt"
        ],
        "properties": {
          "campaignId": {
            "type": "string",
            "format": "uuid"
          },
          "contactId": {
            "type": "string",
            "format": "uuid"
          },
          "templateId": {
            "type": "string",
            "format": "uuid"
          },
          "recipientEmail": {
            "type": "string",
            "maxLength": 320
          },
          "subject": {
            "type": "string",
            "maxLength": 500
          },
          "emailConfigId": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "revision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "channel": {
            "type": "string",
            "enum": [
              "EMAIL"
            ]
          },
          "independentOfBroadcast": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "campaignStateChanged": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "queued": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "providerChecked": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "templateFrozen": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "readAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "CampaignTemplateDeliveryResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "success",
          "data",
          "source"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/CampaignTemplateDelivery"
          },
          "source": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "readAt",
              "providerChecked"
            ],
            "properties": {
              "readAt": {
                "type": "string",
                "format": "date-time"
              },
              "providerChecked": {
                "type": "boolean",
                "enum": [
                  false
                ]
              }
            }
          }
        }
      },
      "CampaignTemplateDelivery": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "deliveryId",
          "channel",
          "state",
          "recipient",
          "createdAt",
          "attemptedAt",
          "scheduledAt",
          "canceledAt",
          "smtpAcceptedAt",
          "deliveredReportAt",
          "deliveryUpdatedAt",
          "deliveryStatus",
          "whatsappAck",
          "whatsappAckAt",
          "reasonCode",
          "reasonAvailability",
          "deliveryUncertain",
          "simulation"
        ],
        "properties": {
          "deliveryId": {
            "type": "string",
            "format": "uuid"
          },
          "channel": {
            "type": "string",
            "enum": [
              "EMAIL",
              "SMS",
              "WHATSAPP",
              "NOTIFICATION",
              "APPMOBILE_NOTIFICATION",
              "UNKNOWN"
            ]
          },
          "state": {
            "type": "string",
            "enum": [
              "INIT",
              "SUCCESS",
              "ERROR",
              "CANCELED",
              "UNKNOWN"
            ]
          },
          "recipient": {
            "$ref": "#/components/schemas/CampaignTemplateRecipient"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "attemptedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "scheduledAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "canceledAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "smtpAcceptedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "deliveredReportAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "deliveryUpdatedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "deliveryStatus": {
            "type": "string",
            "nullable": true,
            "enum": [
              "ACCEPTED",
              "DELIVERED",
              "RELAYED",
              "EXPANDED",
              "DELAYED",
              "ERROR",
              "UNKNOWN",
              null
            ],
            "description": "Recorded email status only, without provider polling. ACCEPTED is SMTP acceptance; DELIVERED is a stored positive delivery report, not proof of inbox placement or reading. null means absent, malformed or not an email row."
          },
          "whatsappAck": {
            "type": "integer",
            "minimum": 0,
            "maximum": 4,
            "nullable": true,
            "description": "Stored WhatsApp acknowledgement only: the current consumer interprets 1 as sent, 2 as received and 3 or greater as read. No new receipt is fetched; null means unavailable or unsupported."
          },
          "whatsappAckAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "reasonCode": {
            "type": "string",
            "nullable": true,
            "enum": [
              "API_PHONE_BAD_COUNTRY",
              "API_PHONE_BAD_FORMAT",
              "API_EMAIL_BAD_FORMAT",
              "API_EMAIL_UNSUBSCRIBE",
              "MAILER_BAD_CONFIG",
              "MAILER_INVALID_RETRY",
              "MAILER_MAX_ATTEMPTS",
              "MAILER_INVALID_ID",
              "MAILER_DELIVERY_UNCERTAIN",
              "DELIVERY_REPORT_FAILED",
              "USER_EMERGENCY_STOP",
              "SMS_TEST_MODE",
              "SMS_CONFIGURATION_ERROR",
              "INVALID_PHONE_NUMBER",
              "SMS_NOT_AVAILABLE",
              "EMPTY_MESSAGE",
              "SMS_QUOTA_EXCEEDED",
              "WHATSAPP_SEND_ERROR",
              "INVALID_WHATSAPP_NUMBER",
              "WHATSAPP_NUMBER_BLOCKED",
              "WHATSAPP_ACCOUNT_NOT_READY",
              "WHATSAPP_NO_ACCOUNT",
              "WHATSAPP_MEDIA_FAILED",
              "WHATSAPP_TEXT_FAILED",
              null
            ],
            "description": "Allowlisted stored errorCode or stopReason only. null means no known safe reason is available, not no failure. Raw provider diagnostics, SMTP responses and errorMessage are never exposed."
          },
          "reasonAvailability": {
            "type": "string",
            "enum": [
              "KNOWN_CODE",
              "UNAVAILABLE"
            ]
          },
          "deliveryUncertain": {
            "type": "boolean",
            "nullable": true,
            "enum": [
              true,
              null
            ],
            "description": "true when an explicit uncertainty marker or MAILER_DELIVERY_UNCERTAIN is recorded. Otherwise null; absence does not establish non-delivery or safe retry."
          },
          "simulation": {
            "type": "boolean",
            "nullable": true
          }
        }
      },
      "CampaignTemplateRecipient": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "contactId",
          "identityStatus",
          "firstName",
          "lastName",
          "email",
          "phone"
        ],
        "properties": {
          "contactId": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "identityStatus": {
            "type": "string",
            "enum": [
              "CURRENT_CONTACT_REFERENCE",
              "SNAPSHOT_ONLY",
              "UNAVAILABLE"
            ],
            "description": "CURRENT_CONTACT_REFERENCE means the stored contact UUID was re-admitted in the current organisation. SNAPSHOT_ONLY means no contact reference was stored. UNAVAILABLE masks identity when a stored reference is invalid, deleted or foreign. Names and destinations are historical send snapshots, never refreshed contact data."
          },
          "firstName": {
            "type": "string",
            "nullable": true,
            "maxLength": 200
          },
          "lastName": {
            "type": "string",
            "nullable": true,
            "maxLength": 200
          },
          "email": {
            "type": "string",
            "nullable": true,
            "maxLength": 320
          },
          "phone": {
            "type": "string",
            "nullable": true,
            "maxLength": 32
          }
        }
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API Key",
        "description": "Format: `ke_live_xxx`"
      },
      "apiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    }
  }
}
```
