POSTSession requiredMessaging

Send the reviewed draft to its selected audience

/api/v1/messages/{id}/send

In-app receipt and optional email jobs commit atomically. Repeat the same message ID and revision after an ambiguous response. Optional email is a private-link alert, requires recipient opt-in and provider configuration, and SMTP acceptance is not delivery confirmation.

Authentication does not grant every action. Company scope, roles and current record access still apply. Protected writes require CSRF verification; company writes also require recent sign-in. Read the authentication guide.

Example request

// Run only in your authorised same-origin test application.
// Replace path placeholders with a record you are allowed to access.
const csrf = document.cookie.split('; ').find(c =>
  c.startsWith('__Host-csrf='))?.slice('__Host-csrf='.length);
if (!csrf) throw new Error('Sign in again before continuing.');
// Supply fields from the request schema; this example is not a complete payload.
const payload = { /* required fields and current revision, if applicable */ };
const response = await fetch('/api/v1/messages/{id}/send', {
  method: 'POST',
  credentials: 'same-origin',
  headers: { 'Content-Type': 'application/json', 'X-CSRF-Token': decodeURIComponent(csrf) },
  body: JSON.stringify(payload),
});
if (!response.ok) throw new Error(`Request failed: ${response.status}`);
// Inspect Content-Type before reading JSON, text or a download.
// A 204 response has no body. Handle errors using the feature guide.

Request parameters

Name	Location	Requirement	Schema
`__Host-session`	cookie	Required	`{"type":"string"}`
`__Host-csrf`	cookie	Required	`{"type":"string"}`
`X-CSRF-Token`	header	Required	`{"type":"string"}`
`Origin`	header	Required	`{"type":"string"}`
`id`	path	Required	`{"format":"uuid","type":"string"}`

Request body

Required body.

`application/json`

Schema: MessageSendInputBody

$schema string · optional: A URL to the JSON Schema for this object.
revision integer · required: See the definition for constraints and nested fields.

Complete schema definition

{
  "additionalProperties": false,
  "properties": {
    "$schema": {
      "description": "A URL to the JSON Schema for this object.",
      "examples": [
        "https://example.com/schemas/MessageSendInputBody.json"
      ],
      "format": "uri",
      "readOnly": true,
      "type": "string"
    },
    "revision": {
      "format": "int64",
      "minimum": 1,
      "type": "integer"
    }
  },
  "required": [
    "revision"
  ],
  "type": "object"
}

Responses

204 No Content

No response body declared.

default Error

application/problem+json

Schema: ErrorModel

$schema string · optional: A URL to the JSON Schema for this object.
detail string · optional: A human-readable explanation specific to this occurrence of the problem.
errors array | null · optional: Optional list of individual error details
instance string · optional: A URI reference that identifies the specific occurrence of the problem.
status integer · optional: HTTP status code
title string · optional: A short, human-readable summary of the problem type. This value should not change between occurrences of the error.
type string · optional: A URI reference to human-readable documentation for the error.

Complete schema definition

{
  "additionalProperties": false,
  "properties": {
    "$schema": {
      "description": "A URL to the JSON Schema for this object.",
      "examples": [
        "https://example.com/schemas/ErrorModel.json"
      ],
      "format": "uri",
      "readOnly": true,
      "type": "string"
    },
    "detail": {
      "description": "A human-readable explanation specific to this occurrence of the problem.",
      "examples": [
        "Property foo is required but is missing."
      ],
      "type": "string"
    },
    "errors": {
      "description": "Optional list of individual error details",
      "items": {
        "$ref": "#/components/schemas/ErrorDetail"
      },
      "type": [
        "array",
        "null"
      ]
    },
    "instance": {
      "description": "A URI reference that identifies the specific occurrence of the problem.",
      "examples": [
        "https://example.com/error-log/abc123"
      ],
      "format": "uri",
      "type": "string"
    },
    "status": {
      "description": "HTTP status code",
      "examples": [
        400
      ],
      "format": "int64",
      "type": "integer"
    },
    "title": {
      "description": "A short, human-readable summary of the problem type. This value should not change between occurrences of the error.",
      "examples": [
        "Bad Request"
      ],
      "type": "string"
    },
    "type": {
      "default": "about:blank",
      "description": "A URI reference to human-readable documentation for the error.",
      "examples": [
        "https://example.com/errors/example"
      ],
      "format": "uri",
      "type": "string"
    }
  },
  "type": "object"
}

The default error response can cover several status codes. Read error handling and retry guidance.

Referenced schemas

Expand a named definition to inspect nested fields and references. The download contains the complete OpenAPI document.

ErrorDetail

{
  "additionalProperties": false,
  "properties": {
    "location": {
      "description": "Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id'",
      "type": "string"
    },
    "message": {
      "description": "Error message text",
      "type": "string"
    },
    "value": {
      "description": "The value at the given location"
    }
  },
  "type": "object"
}

ErrorModel

{
  "additionalProperties": false,
  "properties": {
    "$schema": {
      "description": "A URL to the JSON Schema for this object.",
      "examples": [
        "https://example.com/schemas/ErrorModel.json"
      ],
      "format": "uri",
      "readOnly": true,
      "type": "string"
    },
    "detail": {
      "description": "A human-readable explanation specific to this occurrence of the problem.",
      "examples": [
        "Property foo is required but is missing."
      ],
      "type": "string"
    },
    "errors": {
      "description": "Optional list of individual error details",
      "items": {
        "$ref": "#/components/schemas/ErrorDetail"
      },
      "type": [
        "array",
        "null"
      ]
    },
    "instance": {
      "description": "A URI reference that identifies the specific occurrence of the problem.",
      "examples": [
        "https://example.com/error-log/abc123"
      ],
      "format": "uri",
      "type": "string"
    },
    "status": {
      "description": "HTTP status code",
      "examples": [
        400
      ],
      "format": "int64",
      "type": "integer"
    },
    "title": {
      "description": "A short, human-readable summary of the problem type. This value should not change between occurrences of the error.",
      "examples": [
        "Bad Request"
      ],
      "type": "string"
    },
    "type": {
      "default": "about:blank",
      "description": "A URI reference to human-readable documentation for the error.",
      "examples": [
        "https://example.com/errors/example"
      ],
      "format": "uri",
      "type": "string"
    }
  },
  "type": "object"
}

MessageSendInputBody

{
  "additionalProperties": false,
  "properties": {
    "$schema": {
      "description": "A URL to the JSON Schema for this object.",
      "examples": [
        "https://example.com/schemas/MessageSendInputBody.json"
      ],
      "format": "uri",
      "readOnly": true,
      "type": "string"
    },
    "revision": {
      "format": "int64",
      "minimum": 1,
      "type": "integer"
    }
  },
  "required": [
    "revision"
  ],
  "type": "object"
}

Operation ID: messages-send · Contract 0.0.0-dev