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

# Pledges

OpenAPI 3.0.3 · API 2.0.0

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

## Operations

## POST /promesses/{id}/reminder/preview

Preview one pledge reminder without creating a link

`preview_promesse_reminder`

Required scopes: `promesses:read`, `paiements:read` AND `contacts:read`. Pure preview: no queue, link, reminder journal, cache update, schedule initialization or provider call. The canonical message owner formats this one actionable pledge using validated current allocations, association and currency; settled, canceled, covered or email-less pledges are refused. Monetary outputs are minor units (5000 = 50.00 EUR); the owner input montant is converted from major units. Currency is never guessed or converted; missing historical monetary data is refused. The displayed link is a nonfunctional preview placeholder. Return snapshot must be passed unchanged to send. automaticExcluded describes automatic exclusion only, not a veto on a separately requested manual send. Rest status is informational and does not block a pure preview. No query parameters are accepted. Organisation, API principal and exact scalar references are enforced. Outputs exclude private configuration, raw errors and payment credentials. The rest guard applies when queueing; asynchronous transport and inbox arrival are not guaranteed to occur outside rest periods.  A durable organisation/resource guard also blocks a different request key after PENDING, UNCERTAIN or missing terminal completion proof, even after native minute/day dedupe expires. REMINDER_PREVIOUS_RESULT_UNCERTAIN requires observing and resolving the existing intention in Unisoft; never invent a new key or bypass the guard. Resource claims require positive exact durable insert/CAS acknowledgements. A completion record is written only after a positively acknowledged terminal journal; a stored QUEUED/UPDATED/REFUSED alone cannot grant another owner. Failure of only accessory completion bookkeeping preserves a positively proven effect and retains the guard.

### Authentication

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

### Required permissions

```json
{
  "accepted": "promesses:read",
  "additional": [
    "paiements: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": {},
        "additionalProperties": false
      }
    }
  }
}
```

### Responses

#### HTTP 200

```json
{
  "description": "Observed reminder result.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/PledgeReminderPreview"
          }
        },
        "required": [
          "success",
          "data"
        ]
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_UUID, INVALID_REMINDER_INPUT, EXPLICIT_REST_OVERRIDE_REQUIRED or UNEXPECTED_REQUEST_BODY. Remove unsupported fields and query parameters.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

#### HTTP 401

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

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_PRINCIPAL or CAMPAIGN_RESTRICTED_KEY. Explicit opt-in permissions are required for sending and configuration.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND: a required exact scalar reference is absent, foreign, deleted or outside the allowed campaigns.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "REST_TIME or REST_STATUS_UNAVAILABLE blocks sending. REMINDER_SNAPSHOT_CHANGED, REMINDER_RULES_CHANGED or IDEMPOTENCY_CONFLICT requires reviewing the current intention. PLEDGE_NOT_ACTIONABLE, NO_EMAIL_CHANNEL, REMINDER_RULES_UNINITIALIZED, REMINDER_SENDER_UNAVAILABLE, REMINDER_ASSOCIATION_UNAVAILABLE, INVALID_PLEDGE_HISTORY, INVALID_REMINDER_HISTORY, AMBIGUOUS_REMINDER_RULES or a bounded history/read limit refuses an unavailable dependency. Never retry an uncertain command with a new key.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR. An unknown result does not authorize another send.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "REMINDER_JOURNAL_UNCERTAIN, REMINDER_QUEUE_UNCERTAIN, REMINDER_LINK_UNCERTAIN, REMINDER_TOKEN_UNCERTAIN or REMINDER_RESERVATION_UNCERTAIN. A durable write acknowledgement is missing or contradictory; no new effect or retry is authorized. Observe the existing request using the same identity. REMINDER_RESOURCE_RESERVATION_UNCERTAIN grants no resource owner and permits no later effect.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

### OpenAPI

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

## POST /promesses/{id}/reminder/send

Queue one explicitly requested pledge reminder

`send_promesse_reminder`

Required scopes: `promesses:read`, `paiements:read`, `contacts:read` AND explicit opt-in `promesses:reminders:send`. Send one email for exactly this pledge, using the current validated pledge balance and the canonical pledge message model. First call preview and preserve its snapshot; a changed balance, contact, allocation, model or sender rejects with REMINDER_SNAPSHOT_CHANGED before sending. Snapshot checks are optimistic separate reads, not a transaction with internal writers. Journal the command before creating the payment link or queue item; the command is bound to the API principal, organisation and idempotencyKey. Reusing the same key and exact input reads the existing result; changed input returns IDEMPOTENCY_CONFLICT. A PENDING or UNCERTAIN command must only be observed, never retried with another key. The native daily UTC deduplication can return REFUSED/REMINDER_ALREADY_QUEUED. Chabbat and Yom Tov are checked by the canonical calendar in Europe/Paris; REST_TIME blocks sending. forceRest=true requires restOverrideReason and the user explicit request to override that rest period; never set it automatically after refusal. Configuration exclusions concern automatic reminders only; a manual send remains an explicit separate intention. QUEUED means recorded in the email queue, never delivered. Read the command to observe QUEUED_OR_IN_FLIGHT, SMTP_ACCEPTED or an explicit DELIVERED report. SMTP_ACCEPTED does not prove inbox delivery. deliveryRead=UNAVAILABLE means the optional delivery observation failed; it does not cancel the command. No query parameters are accepted. Organisation, API principal and exact scalar references are enforced. Outputs exclude private configuration, raw errors and payment credentials. The rest guard applies when queueing; asynchronous transport and inbox arrival are not guaranteed to occur outside rest periods.  A durable organisation/resource guard also blocks a different request key after PENDING, UNCERTAIN or missing terminal completion proof, even after native minute/day dedupe expires. REMINDER_PREVIOUS_RESULT_UNCERTAIN requires observing and resolving the existing intention in Unisoft; never invent a new key or bypass the guard. Resource claims require positive exact durable insert/CAS acknowledgements. A completion record is written only after a positively acknowledged terminal journal; a stored QUEUED/UPDATED/REFUSED alone cannot grant another owner. Failure of only accessory completion bookkeeping preserves a positively proven effect and retains the guard.

### Authentication

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

### Required permissions

```json
{
  "accepted": "promesses:reminders:send",
  "additional": [
    "promesses:read",
    "paiements: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"
          },
          "expectedSnapshot": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "forceRest": {
            "type": "boolean"
          },
          "restOverrideReason": {
            "type": "string",
            "minLength": 1,
            "maxLength": 500,
            "pattern": "\\S"
          }
        },
        "required": [
          "idempotencyKey",
          "expectedSnapshot"
        ],
        "additionalProperties": false,
        "oneOf": [
          {
            "type": "object",
            "properties": {
              "forceRest": {
                "type": "boolean",
                "enum": [
                  true
                ]
              }
            },
            "required": [
              "forceRest",
              "restOverrideReason"
            ],
            "additionalProperties": true
          },
          {
            "type": "object",
            "properties": {
              "forceRest": {
                "type": "boolean",
                "enum": [
                  false
                ]
              }
            },
            "additionalProperties": true,
            "not": {
              "required": [
                "restOverrideReason"
              ]
            }
          }
        ]
      }
    }
  }
}
```

### Responses

#### HTTP 200

```json
{
  "description": "Observed reminder result.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/PledgeReminderCommand"
          }
        },
        "required": [
          "success",
          "data"
        ]
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_UUID, INVALID_REMINDER_INPUT, EXPLICIT_REST_OVERRIDE_REQUIRED or UNEXPECTED_REQUEST_BODY. Remove unsupported fields and query parameters.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

#### HTTP 401

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

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_PRINCIPAL or CAMPAIGN_RESTRICTED_KEY. Explicit opt-in permissions are required for sending and configuration.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND: a required exact scalar reference is absent, foreign, deleted or outside the allowed campaigns.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "REST_TIME or REST_STATUS_UNAVAILABLE blocks sending. REMINDER_SNAPSHOT_CHANGED, REMINDER_RULES_CHANGED or IDEMPOTENCY_CONFLICT requires reviewing the current intention. PLEDGE_NOT_ACTIONABLE, NO_EMAIL_CHANNEL, REMINDER_RULES_UNINITIALIZED, REMINDER_SENDER_UNAVAILABLE, REMINDER_ASSOCIATION_UNAVAILABLE, INVALID_PLEDGE_HISTORY, INVALID_REMINDER_HISTORY, AMBIGUOUS_REMINDER_RULES or a bounded history/read limit refuses an unavailable dependency. Never retry an uncertain command with a new key.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR. An unknown result does not authorize another send.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "REMINDER_JOURNAL_UNCERTAIN, REMINDER_QUEUE_UNCERTAIN, REMINDER_LINK_UNCERTAIN, REMINDER_TOKEN_UNCERTAIN or REMINDER_RESERVATION_UNCERTAIN. A durable write acknowledgement is missing or contradictory; no new effect or retry is authorized. Observe the existing request using the same identity. REMINDER_RESOURCE_RESERVATION_UNCERTAIN grants no resource owner and permits no later effect.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

### OpenAPI

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

## GET /promesses/reminders/commands/{requestId}

Observe a pledge reminder command and recorded delivery

`get_promesse_reminder_command`

Read-only command observation for the same organisation and API principal that sent it. Requires promesses:reminders:send, promesses:read, paiements:read and contacts:read. Each target is reauthorized against current allowed campaigns. PENDING or UNCERTAIN is not a failed send and never authorizes retry. QUEUED_OR_IN_FLIGHT cannot distinguish waiting from an active worker; SMTP_ACCEPTED is provider acceptance only. DELIVERED requires an explicit delivery report and deliveredAt. UNKNOWN or deliveryRead=UNAVAILABLE leaves delivery unknown. No provider polling, resend or retry occurs. No query parameters are accepted. Organisation, API principal and exact scalar references are enforced. Outputs exclude private configuration, raw errors and payment credentials. The rest guard applies when queueing; asynchronous transport and inbox arrival are not guaranteed to occur outside rest periods.  A durable organisation/resource guard also blocks a different request key after PENDING, UNCERTAIN or missing terminal completion proof, even after native minute/day dedupe expires. REMINDER_PREVIOUS_RESULT_UNCERTAIN requires observing and resolving the existing intention in Unisoft; never invent a new key or bypass the guard. Resource claims require positive exact durable insert/CAS acknowledgements. A completion record is written only after a positively acknowledged terminal journal; a stored QUEUED/UPDATED/REFUSED alone cannot grant another owner. Failure of only accessory completion bookkeeping preserves a positively proven effect and retains the guard.

### Authentication

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

### Required permissions

```json
{
  "accepted": "promesses:reminders:send",
  "additional": [
    "promesses:read",
    "paiements:read",
    "contacts:read"
  ]
}
```

### Parameters

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

### Responses

#### HTTP 200

```json
{
  "description": "Observed reminder result.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/PledgeReminderCommand"
          }
        },
        "required": [
          "success",
          "data"
        ]
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_UUID, INVALID_REMINDER_INPUT, EXPLICIT_REST_OVERRIDE_REQUIRED or UNEXPECTED_REQUEST_BODY. Remove unsupported fields and query parameters.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

#### HTTP 401

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

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_PRINCIPAL or CAMPAIGN_RESTRICTED_KEY. Explicit opt-in permissions are required for sending and configuration.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND: a required exact scalar reference is absent, foreign, deleted or outside the allowed campaigns.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "REST_TIME or REST_STATUS_UNAVAILABLE blocks sending. REMINDER_SNAPSHOT_CHANGED, REMINDER_RULES_CHANGED or IDEMPOTENCY_CONFLICT requires reviewing the current intention. PLEDGE_NOT_ACTIONABLE, NO_EMAIL_CHANNEL, REMINDER_RULES_UNINITIALIZED, REMINDER_SENDER_UNAVAILABLE, REMINDER_ASSOCIATION_UNAVAILABLE, INVALID_PLEDGE_HISTORY, INVALID_REMINDER_HISTORY, AMBIGUOUS_REMINDER_RULES or a bounded history/read limit refuses an unavailable dependency. Never retry an uncertain command with a new key.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR. An unknown result does not authorize another send.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "REMINDER_JOURNAL_UNCERTAIN, REMINDER_QUEUE_UNCERTAIN, REMINDER_LINK_UNCERTAIN, REMINDER_TOKEN_UNCERTAIN or REMINDER_RESERVATION_UNCERTAIN. A durable write acknowledgement is missing or contradictory; no new effect or retry is authorized. Observe the existing request using the same identity. REMINDER_RESOURCE_RESERVATION_UNCERTAIN grants no resource owner and permits no later effect.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

### OpenAPI

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

## GET /promesses/reminders/rules

Read automatic pledge reminder rules and exclusions

`get_promesse_reminder_rules`

Requires promesses:read AND contacts:read and an organisation-wide key; campaign-restricted keys are refused because these rules configure the whole organisation. Read-only: absent configuration returns initialized=false and documented defaults without inserting anything. channel is always EMAIL; frequency is days 1..365, graceDays is 7. excludeContacts are exact CRM contact UUIDs excluded from automatic reminders only. template and subject are organization-authored text with canonical variables {prenom}, {nom}, {organisation}, {liste}, {total}, {nombre}, {lien}; the owner appends the payment link if omitted. The existing cron enforces rest periods; changing rules never runs it immediately. revision is an opaque optimistic concurrency token. No query parameters are accepted. Organisation, API principal and exact scalar references are enforced. Outputs exclude private configuration, raw errors and payment credentials. The rest guard applies when queueing; asynchronous transport and inbox arrival are not guaranteed to occur outside rest periods.  A durable organisation/resource guard also blocks a different request key after PENDING, UNCERTAIN or missing terminal completion proof, even after native minute/day dedupe expires. REMINDER_PREVIOUS_RESULT_UNCERTAIN requires observing and resolving the existing intention in Unisoft; never invent a new key or bypass the guard. Resource claims require positive exact durable insert/CAS acknowledgements. A completion record is written only after a positively acknowledged terminal journal; a stored QUEUED/UPDATED/REFUSED alone cannot grant another owner. Failure of only accessory completion bookkeeping preserves a positively proven effect and retains the guard.

### Authentication

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

### Required permissions

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

### Responses

#### HTTP 200

```json
{
  "description": "Observed reminder result.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/PledgeReminderRules"
          }
        },
        "required": [
          "success",
          "data"
        ]
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_UUID, INVALID_REMINDER_INPUT, EXPLICIT_REST_OVERRIDE_REQUIRED or UNEXPECTED_REQUEST_BODY. Remove unsupported fields and query parameters.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

#### HTTP 401

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

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_PRINCIPAL or CAMPAIGN_RESTRICTED_KEY. Explicit opt-in permissions are required for sending and configuration.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND: a required exact scalar reference is absent, foreign, deleted or outside the allowed campaigns.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "REST_TIME or REST_STATUS_UNAVAILABLE blocks sending. REMINDER_SNAPSHOT_CHANGED, REMINDER_RULES_CHANGED or IDEMPOTENCY_CONFLICT requires reviewing the current intention. PLEDGE_NOT_ACTIONABLE, NO_EMAIL_CHANNEL, REMINDER_RULES_UNINITIALIZED, REMINDER_SENDER_UNAVAILABLE, REMINDER_ASSOCIATION_UNAVAILABLE, INVALID_PLEDGE_HISTORY, INVALID_REMINDER_HISTORY, AMBIGUOUS_REMINDER_RULES or a bounded history/read limit refuses an unavailable dependency. Never retry an uncertain command with a new key.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR. An unknown result does not authorize another send.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "REMINDER_JOURNAL_UNCERTAIN, REMINDER_QUEUE_UNCERTAIN, REMINDER_LINK_UNCERTAIN, REMINDER_TOKEN_UNCERTAIN or REMINDER_RESERVATION_UNCERTAIN. A durable write acknowledgement is missing or contradictory; no new effect or retry is authorized. Observe the existing request using the same identity. REMINDER_RESOURCE_RESERVATION_UNCERTAIN grants no resource owner and permits no later effect.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

### OpenAPI

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

## PATCH /promesses/reminders/rules

Change automatic pledge reminder rules and contact exclusions

`update_promesse_reminder_rules`

Requires explicit opt-in promesses:reminders:write plus promesses:read and contacts:read; campaign-restricted keys are refused. Read rules first and pass expectedRevision. Only patch.active, frequency, excludeContacts, template and subject are writable. Missing fields remain unchanged; excludeContacts replaces the whole automatic-only exclusion list, with at most 1000 unique CRM UUIDs in the organisation. Empty template/subject restores the owner default. No email, payment link or cron execution is initiated. Command is journaled before a compare-and-set write against the admitted config fields; REMINDER_RULES_CHANGED refuses stale input. The configuration must already exist (initialized=true); REMINDER_RULES_UNINITIALIZED requires initial setup in Unisoft, because safely creating a missing legacy singleton has no unique owner index. The exact idempotencyKey/input returns the prior result and never reruns an uncertain write. No query parameters are accepted. Organisation, API principal and exact scalar references are enforced. Outputs exclude private configuration, raw errors and payment credentials. The rest guard applies when queueing; asynchronous transport and inbox arrival are not guaranteed to occur outside rest periods.  A durable organisation/resource guard also blocks a different request key after PENDING, UNCERTAIN or missing terminal completion proof, even after native minute/day dedupe expires. REMINDER_PREVIOUS_RESULT_UNCERTAIN requires observing and resolving the existing intention in Unisoft; never invent a new key or bypass the guard. Resource claims require positive exact durable insert/CAS acknowledgements. A completion record is written only after a positively acknowledged terminal journal; a stored QUEUED/UPDATED/REFUSED alone cannot grant another owner. Failure of only accessory completion bookkeeping preserves a positively proven effect and retains the guard.

### Authentication

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

### Required permissions

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

### 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}$"
          },
          "patch": {
            "type": "object",
            "minProperties": 1,
            "properties": {
              "active": {
                "type": "boolean"
              },
              "frequency": {
                "type": "integer",
                "minimum": 1,
                "maximum": 365
              },
              "excludeContacts": {
                "type": "array",
                "maxItems": 1000,
                "uniqueItems": true,
                "items": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "template": {
                "type": "string",
                "maxLength": 4000
              },
              "subject": {
                "type": "string",
                "maxLength": 200
              }
            },
            "additionalProperties": false
          }
        },
        "required": [
          "idempotencyKey",
          "expectedRevision",
          "patch"
        ],
        "additionalProperties": false
      }
    }
  }
}
```

### Responses

#### HTTP 200

```json
{
  "description": "Observed reminder result.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/PledgeReminderCommand"
          }
        },
        "required": [
          "success",
          "data"
        ]
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "INVALID_UUID, INVALID_REMINDER_INPUT, EXPLICIT_REST_OVERRIDE_REQUIRED or UNEXPECTED_REQUEST_BODY. Remove unsupported fields and query parameters.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

#### HTTP 401

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

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE, INVALID_PRINCIPAL or CAMPAIGN_RESTRICTED_KEY. Explicit opt-in permissions are required for sending and configuration.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND: a required exact scalar reference is absent, foreign, deleted or outside the allowed campaigns.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

#### HTTP 409

```json
{
  "description": "REST_TIME or REST_STATUS_UNAVAILABLE blocks sending. REMINDER_SNAPSHOT_CHANGED, REMINDER_RULES_CHANGED or IDEMPOTENCY_CONFLICT requires reviewing the current intention. PLEDGE_NOT_ACTIONABLE, NO_EMAIL_CHANNEL, REMINDER_RULES_UNINITIALIZED, REMINDER_SENDER_UNAVAILABLE, REMINDER_ASSOCIATION_UNAVAILABLE, INVALID_PLEDGE_HISTORY, INVALID_REMINDER_HISTORY, AMBIGUOUS_REMINDER_RULES or a bounded history/read limit refuses an unavailable dependency. Never retry an uncertain command with a new key.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

#### HTTP 500

```json
{
  "description": "INTERNAL_ERROR. An unknown result does not authorize another send.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

#### HTTP 503

```json
{
  "description": "REMINDER_JOURNAL_UNCERTAIN, REMINDER_QUEUE_UNCERTAIN, REMINDER_LINK_UNCERTAIN, REMINDER_TOKEN_UNCERTAIN or REMINDER_RESERVATION_UNCERTAIN. A durable write acknowledgement is missing or contradictory; no new effect or retry is authorized. Observe the existing request using the same identity. REMINDER_RESOURCE_RESERVATION_UNCERTAIN grants no resource owner and permits no later effect.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "error"
        ]
      }
    }
  }
}
```

### OpenAPI

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

## Schemas

```json
{
  "components": {
    "schemas": {
      "PledgeReminderPreview": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "pledgeId": {
            "type": "string",
            "format": "uuid"
          },
          "contactId": {
            "type": "string",
            "format": "uuid"
          },
          "channel": {
            "type": "string",
            "enum": [
              "EMAIL"
            ]
          },
          "subject": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "snapshot": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "amountMinor": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          },
          "paidMinor": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          },
          "remainingMinor": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          },
          "currency": {
            "type": "string",
            "pattern": "^[a-z]{3}$"
          },
          "assoc": {
            "type": "string"
          },
          "automaticExcluded": {
            "type": "boolean"
          },
          "rest": {
            "$ref": "#/components/schemas/PledgeReminderRest"
          },
          "linkIsPreview": {
            "type": "boolean",
            "enum": [
              true
            ]
          }
        },
        "required": [
          "pledgeId",
          "contactId",
          "channel",
          "subject",
          "message",
          "snapshot",
          "amountMinor",
          "paidMinor",
          "remainingMinor",
          "currency",
          "assoc",
          "automaticExcluded",
          "rest",
          "linkIsPreview"
        ]
      },
      "PledgeReminderRest": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "blocked": {
            "type": "boolean"
          },
          "reason": {
            "type": "string",
            "nullable": true
          },
          "until": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "timeZone": {
            "type": "string",
            "enum": [
              "Europe/Paris"
            ]
          }
        },
        "required": [
          "blocked",
          "reason",
          "until",
          "timeZone"
        ]
      },
      "PledgeReminderCommand": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "requestId": {
            "type": "string",
            "format": "uuid"
          },
          "action": {
            "type": "string",
            "enum": [
              "SEND",
              "RULES"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "PENDING",
              "QUEUED",
              "UPDATED",
              "REFUSED",
              "UNCERTAIN"
            ]
          },
          "requestedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "completedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "targetIds": {
            "type": "array",
            "maxItems": 50,
            "items": {
              "type": "string"
            }
          },
          "error": {
            "type": "string",
            "nullable": true
          },
          "outcomes": {
            "type": "array",
            "maxItems": 50,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "targetId": {
                  "type": "string"
                },
                "status": {
                  "type": "string",
                  "enum": [
                    "QUEUED",
                    "DUPLICATE",
                    "REFUSED",
                    "UNCERTAIN"
                  ]
                }
              },
              "required": [
                "targetId",
                "status"
              ]
            }
          },
          "retryable": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "deliveryRead": {
            "type": "string",
            "enum": [
              "AVAILABLE",
              "UNAVAILABLE"
            ]
          },
          "deliveries": {
            "type": "array",
            "maxItems": 50,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "targetId": {
                  "type": "string"
                },
                "sendId": {
                  "type": "string",
                  "format": "uuid"
                },
                "state": {
                  "type": "string",
                  "enum": [
                    "QUEUED_OR_IN_FLIGHT",
                    "SMTP_ACCEPTED",
                    "DELIVERED",
                    "FAILED",
                    "CANCELED",
                    "UNCERTAIN",
                    "UNKNOWN"
                  ]
                }
              },
              "required": [
                "targetId",
                "sendId",
                "state"
              ]
            }
          }
        },
        "required": [
          "requestId",
          "action",
          "status",
          "requestedAt",
          "completedAt",
          "targetIds",
          "error",
          "outcomes",
          "retryable",
          "deliveryRead",
          "deliveries"
        ]
      },
      "PledgeReminderRules": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "active": {
            "type": "boolean"
          },
          "frequency": {
            "type": "integer",
            "minimum": 1,
            "maximum": 365
          },
          "excludeContacts": {
            "type": "array",
            "maxItems": 1000,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "format": "uuid"
            }
          },
          "template": {
            "type": "string",
            "maxLength": 4000
          },
          "subject": {
            "type": "string",
            "maxLength": 200
          },
          "revision": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "initialized": {
            "type": "boolean"
          },
          "channel": {
            "type": "string",
            "enum": [
              "EMAIL"
            ]
          },
          "graceDays": {
            "type": "integer",
            "enum": [
              7
            ]
          },
          "exclusionScope": {
            "type": "string",
            "enum": [
              "AUTOMATIC_ONLY"
            ]
          },
          "timeZone": {
            "type": "string",
            "enum": [
              "Europe/Paris"
            ]
          }
        },
        "required": [
          "active",
          "frequency",
          "excludeContacts",
          "template",
          "subject",
          "revision",
          "initialized",
          "channel",
          "graceDays",
          "exclusionScope",
          "timeZone"
        ]
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API Key",
        "description": "Format: `ke_live_xxx`"
      },
      "apiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    }
  }
}
```
