File inbound mail as a document

Módulo Platform

POST/inbound-messages/{id}/fileinboundMessages.file

Files verified project inbox mail as a Document record of the project, optionally to a record of the project the caller can open (app.file_inbound_message); the subject, sender and text are posted as a comment on the document and the record. Mail is filed once (inbound_message_triaged: 422); unverified mail is refused (inbound_message_unverified: 422). Requires `Idempotency-Key`; a replay returns the original response. A rule that refuses the request returns 422 with `refusal` and `reason`.

Requiere la capacidad knowledge.document.write.
Alcances de OAuth: knowledge.
Envía el encabezado Idempotency-Key. Una repetición con la misma clave devuelve la respuesta original.
Estados de error: 400, 401, 404, 409, 422, 429. Los errores son detalles de problema RFC 9457.

Parámetros de ruta y de consulta

inboundMessages.file: Parámetros de ruta y de consulta
Campo	Tipo	Obligatorio	Descripción
id	string (uuid)	Sí	Identifier of the inbound message.

Cuerpo de la solicitud: InboundMessageFileRequest

inboundMessages.file: InboundMessageFileRequest
Campo	Tipo	Obligatorio	Descripción
title	string	No	Document title; the subject when omitted.Restricciones: length 1 to 200
record_id	string (uuid)	No	Identifier of the record of the project to file the mail to.

{
  "title": "Rigging plot v4",
  "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f"
}

Respuesta 200: InboundMessage

inboundMessages.file: InboundMessage
Campo	Tipo	Obligatorio	Descripción
id	string (uuid)	Sí	Identifier of the inbound message.
org_id	string (uuid)	Sí	Identifier of the owning organization, derived from the parent row and never accepted from the caller.
created_at	string (date-time)	Sí	When the row was created.
created_by	string (uuid) \| null	Sí	Identifier of the person who created the row.
updated_at	string (date-time)	Sí	When the row was last updated.
updated_by	string (uuid) \| null	Sí	Identifier of the person who last updated the row.
purpose	"Project Inbox" \| "Reply"	Sí	What the mail was sent to.
inbound_address_id	string (uuid) \| null	Sí	Identifier of the project inbox the mail was sent to.
from_address	string	Sí	Sender address.Restricciones: length 1 to 320
subject_line	string \| null	Sí	Subject.Restricciones: length 1 to 998
body_text	string \| null	Sí	Plain-text body with quoted text stripped.Restricciones: length 1 to 20000
dkim_verified	boolean	Sí	True when the sender's DKIM signature verified.
inbound_status	"Received" \| "Verified" \| "Filed" \| "Rejected"	Sí	Processing status.
rejection_reason	string \| null	Sí	Why the mail was rejected.Restricciones: length 1 to 500
received_at	string (date-time)	Sí	When the mail arrived.
filed_document_id	string (uuid) \| null	Sí	Identifier of the document the mail was filed as.
filed_record_id	string (uuid) \| null	Sí	Identifier of the record of the project the mail was filed to.
filed_by	string (uuid) \| null	Sí	Identifier of the person who filed the mail.
filed_at	string (date-time) \| null	Sí	When the mail was filed.
discarded_at	string (date-time) \| null	Sí	When the mail was discarded.
discarded_by	string (uuid) \| null	Sí	Identifier of the person who discarded the mail.
discard_reason	string \| null	Sí	Why the mail was discarded.Restricciones: length 1 to 500

{
  "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "created_at": "2026-10-08T14:30:00Z",
  "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "updated_at": "2026-10-08T14:30:00Z",
  "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "purpose": "Project Inbox",
  "inbound_address_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "from_address": "rigging@bayside-audio.test",
  "subject_line": "Rigging plot v4",
  "body_text": "Updated plot attached.",
  "dkim_verified": true,
  "inbound_status": "Verified",
  "rejection_reason": "DKIM failed.",
  "received_at": "2026-10-08T14:30:00Z",
  "filed_document_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "filed_record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "filed_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "filed_at": "2026-10-08T14:30:00Z",
  "discarded_at": "2026-10-08T14:30:00Z",
  "discarded_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "discard_reason": "Spam."
}

Ejemplos de código

curl -X POST "$XOS_BASE_URL/inbound-messages/0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f/file" \
  -H "Authorization: Bearer $XOS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"title":"Rigging plot v4","record_id":"0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f"}'

const { data } = await xos.inboundMessages.file("0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", {
    "title": "Rigging plot v4",
    "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f"
  });

response = xos.inbound_messages.file("0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", {"title": "Rigging plot v4", "record_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f"})

xos inbound-messages file 0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f --data '{"title":"Rigging plot v4","record_id":"0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f"}'