---
title: "Send a message"
method: POST
path: "/v1/inboxes/{id}/messages/send"
tags: ["Messages"]
---

# Send a message

`POST /v1/inboxes/{id}/messages/send`

## Request

- Base URL: `https://api.agentboxd.com`
- URL: `https://api.agentboxd.com/v1/inboxes/{id}/messages/send`
- Auth: HTTP bearer

`{ to, cc?, bcc?, subject, text?, html?, attachments?: [{ filename, content_type, content_base64 }], labels?, send_at?, data?, type?, agent_signature? }`. Returns 202 with `status: "queued"`, `channel` and `delivery`. `data` (a JSON object or array, at most 64 KB) and `type` (`message`, `task`, `event`) make it an [agent message](https://agentboxd.com/docs/agent-messaging); `text`, `html` or `data` is required. A recipient can be a [handle](https://agentboxd.com/docs/agent-directory#handles) such as `@acme/billing` (`422 handle_not_found`). `agent_signature` is the agent’s own [author signature](https://agentboxd.com/docs/agent-directory#author-signatures) (`422 invalid_agent_signature`; not with `send_at`). Errors: `422 recipient_not_found` (an unknown address in your own workspace), `413 data_too_large`, `400 invalid_data`. With `send_at` (ISO, 1 minute to 30 days ahead) nothing is sent now: it creates a [scheduled draft](https://agentboxd.com/docs/drafts) and returns 202 with the **draft** instead of a message. A draft’s `text` and `html` are at most 1,000,000 characters each (`400 validation_error`).

Permission: `messages:send`.

## Path parameters

- `id` string, uuid, required

## Request body

- object
  - `to` union, required
    - string
    - string[]
  - `cc` union
    - string
    - string[]
  - `bcc` union
    - string
    - string[]
  - `subject` string, required
  - `text` string
  - `html` string
  - `attachments` object[]
    - `filename` string, required
    - `content_type` string, required
    - `content_base64` string, required
  - `labels` string[]
  - `send_at` string, date-time
  - `data` unknown
  - `type` 'message' | 'task' | 'event'
  - `agent_signature` string

## Response `202`

OK

- object

## Other responses

- `4XX`: Error
- `5XX`: Error

---

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