---
title: "Create a new message"
method: POST
path: "/public/v1/messages"
tags: ["public"]
---

# Create a new message

`POST /public/v1/messages`

## Request

- Base URL: `https://api.gurusup.com`
- URL: `https://api.gurusup.com/public/v1/messages`
- Auth: API key in header `x-api-key`

Send a new message to the specified thread.

## Request body

- CreateMessageRequest (unresolved $ref)

## Response `200`

Stable documented message fields. Public v1 may also return legacy properties; clients should ignore response properties they do not use.

- MessageResponse: Stable message fields; public v1 may return additional legacy properties.
  - `fid` string, nullable: Foreign identifier supplied by the integration
  - `body` string, nullable: Message content/body text
  - `subject` string, nullable: Message subject (email-type threads)
  - `translated_body` string, nullable: Translated body, when the message was translated
  - `translated_subject` string, nullable: Translated subject, when applicable
  - `chat_body` string[], nullable: Body split into chat bubbles (chat-type threads)
  - `language` string, nullable: Detected language code (e.g. 'es', 'en')
  - `thread` string, required: Thread hash identifier
  - `thread_fid` string, required: Thread foreign identifier
  - `thread_format` string, nullable: Thread format ('email' or 'chat')
  - `user_fid` string, nullable: Sender identifier (email, phone, or user id)
  - `sender_name` string, nullable: Display name of the sender
  - `to` string, nullable: Recipient address (email or phone)
  - `cc` string[], nullable: CC recipients
  - `integration_code` string, required: Integration source code (e.g. 'API', 'WHATSAPP', 'GMAIL')
  - `is_customer_support_agent` boolean: True if sent by a human support agent
  - `is_auto_reply` boolean: True if generated as an automatic reply
  - `read` boolean: Whether the message has been read
  - `archived` boolean: Whether the message is archived
  - `is_translated` boolean: Whether the message was translated
  - `timestamp` string, date-time, required: Message timestamp
  - `original_platform_url` string, nullable: Link to the message in the source platform
  - `delivery_status` string, nullable: Delivery status, when tracked by the channel
  - `delivery_error_code` integer, nullable: Channel error code for a failed delivery
  - `delivery_error_category` string, nullable: Customer-safe delivery error category
  - `delivery_retriable` boolean, nullable: Whether retrying the delivery may succeed
  - `delivery_status_updated_at` string, date-time, nullable: When delivery status last changed
  - `attachments` AttachmentResponse[], nullable: Message attachments (no raw data)
    - `filename` string, required: File name including extension
    - `file_type` string, nullable: MIME type of the file
    - `url` string, nullable: URL to fetch the attachment, when available
    - `description` string, nullable: Transcription/description, when available

## Other responses

- `201`: Message from a support agent (`is_customer_support_agent: true`). The thread is archived and a lightweight acknowledgement is returned instead of the full message.
- `400`: Invalid request or business rule violation.
- `401`: Missing or invalid API key. Auth errors use a distinct `{error_code, message}` envelope.
- `404`: The requested resource was not found.
- `409`: A message with the same `fid` already exists.
- `422`: Request body validation failed.
- `429`: Rate limit exceeded — retry later. Rate-limit errors use a distinct `{error}` envelope.
- `503`: Transient upstream/provider error — safe to retry.

---

[API](https://skmtc.dev/gurusup/apis/gurusup-api.md) · [All operations](https://skmtc.dev/gurusup/apis/gurusup-api/llms.txt) · [OpenAPI document](https://skmtc.dev/gurusup/apis/gurusup-api/revisions/8b3c86d4bf1e?raw)