---
title: "Submit a new message to the system."
method: POST
path: "/api/v1/messages"
tags: ["Message"]
---

# Submit a new message to the system.

`POST /api/v1/messages`

Push a new message to the systems outbound message queue. The system will continuously attempt to send the message until
it is either fully transmitted, or the send deadline is expired.

## Query parameters

- `reply_timeout` integer

## Request body

- PushMessageBody — A message to send to a given receiver
  - `dst` union
    - object — An IP in the subnet of the receiver node
      - `ip` string, ipv6 — The target IP of the message
    - object — The hex encoded public key of the receiver node
      - `pk` string — The hex encoded public key of the target node
  - `topic` string, byte — An optional message topic
  - `payload` string, byte — The message to send, base64 encoded

## Response `200`

We received a reply within the specified timeout

- InboundMessage — A message received by the system
  - `id` string, hex — Id of the message, hex encoded
  - `srcIp` string, ipv6 — Sender overlay IP address
  - `srcPk` string, hex — Sender public key, hex encoded
  - `dstIp` string, ipv6 — Receiver overlay IP address
  - `dstPk` string, hex — Receiver public key, hex encoded. This is the public key of the system
  - `topic` string, byte — An optional message topic
  - `payload` string, byte — The message payload, encoded in standard alphabet base64

## Other responses

- `201` — Message pushed successfully, and not waiting for a reply
- `408` — The system timed out waiting for a reply to the message

## Changes

- **2023-11-15** `3dfb2fb733d5` — 2 info
  - added the new optional request property `topic`
  - added the optional property `topic` to the response with the `200` status
- **2023-11-03** `dc2a386974c6` — 4 warning, 4 info
  - removed the optional property `dst_ip` from the response with the `200` status
  - removed the optional property `dst_pk` from the response with the `200` status
  - removed the optional property `src_ip` from the response with the `200` status
  - removed the optional property `src_pk` from the response with the `200` status
  - …4 more
- **2023-11-02** `e0eba3e5e2bc` — 8 info
  - added the new optional `query` request parameter `reply_timeout`
  - added the non-success response with the status `408`
  - added the optional property `dst_ip` to the response with the `200` status
  - added the optional property `dst_pk` to the response with the `200` status
  - …4 more
- **2023-10-27** `15ac72e8d54f` — 1 breaking, 1 info
  - the `dst` request property type/format changed from `string`/`ipv6` to ``/``
  - added `subschema #1, subschema #2` to the `dst` request property `oneOf` list
- **2023-10-27** `0ebb5659d3ca` — 1 info
  - endpoint added

[Full history](https://skmtc.dev/threefoldtech/apis/mycelium-management/changes/api/v1/messages/post.md)

---

[API](https://skmtc.dev/threefoldtech/apis/mycelium-management.md) · [All operations](https://skmtc.dev/threefoldtech/apis/mycelium-management/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/threefoldtech/mycelium-management/revisions/65042c1a7b84/schema)