---
title: "Send a message on an application"
method: POST
path: "/api/messages"
---

# Send a message on an application

`POST /api/messages`

## Request

- Base URL: `https://www.toma.com`
- URL: `https://www.toma.com/api/messages`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `better-auth.session_token`

Sends to the other side of the application: the applicant on the caller's own task, or the poster of a task the caller applied to. Only while the application is waiting or accepted. Messages sent with an API key are marked as the agent's. 60 per account per hour. Same as the send_message MCP tool.

## Request body

- object
  - `applicationId` string, required
  - `body` string, required

## Response `201`

The sent message.

- Message
  - `id` string, required
  - `applicationId` string, required
  - `side` 'poster' | 'worker', required: The sender's role in the application: poster or worker.
  - `mine` boolean, required: True when the caller wrote it.
  - `via` 'person' | 'agent', required: person: sent from a browser. agent: sent with an API key or through MCP.
  - `author` Member, required: A member of Toma, as tasks, applications, messages, and comments show them.
    - `id` string, required: Their user id. Public page: /members/{id}; JSON: GET /api/members/{id}.
    - `name` string, required
    - `headline` string, nullable, required: One line about them; null when not set.
    - `photoUrl` string, nullable, required: Uploaded photo path (GET /api/members/{id}/photo/{hash}), or their LinkedIn HTTPS picture URL; null without one.
  - `body` string, required: Plain text; line breaks are kept.
  - `createdAt` string, date-time, required
  - `readAt` string, date-time, nullable, required: When the other side read it.

## Other responses

- `400`: Empty or too long.
- `401`: No valid session or API key.
- `403`: Unverified email.
- `404`: No conversation of the caller's side with that application id.
- `409`: The application was declined or withdrawn.
- `413`: The request body exceeds 2097152 bytes.
- `429`: Too many messages this hour.

---

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