---
title: "Relay a message envelope to the connector's service as the signed-in person [write]"
method: POST
path: "/workspace-connectors/{id}/ingest/messages"
tags: ["workspace-connectors"]
---

# Relay a message envelope to the connector's service as the signed-in person \[write\]

`POST /workspace-connectors/{id}/ingest/messages`

## Request

- Base URL: `https://api.agentsky.dev/v1`
- URL: `https://api.agentsky.dev/v1/workspace-connectors/{id}/ingest/messages`
- Auth: HTTP bearer

{id} is a connector id or a kind (the oldest connector of that kind answers). The person's workspace role picks the connector's vault; the vault's credential (a <KIND>_API_KEY environment secret, or a bearer secret for the service's host) goes on a POST to {origin}/v1/ingest/messages and never reaches the caller. The body is the service's message envelope, or an array of them, and passes through unchanged (JSON, at most 1 MiB); Idempotency-Key passes through, defaulting to the envelope's external_message_id or id, or for an array to a digest of its envelopes' ids. ?sync=true passes through (the CRM then ingests inline for at most 100 envelopes); otherwise the service may answer 202 {data:{inbox_id,count,status}} and ingest later, which GET ../ingest/inbox/{inbox_id} follows. The answer is the service's status and body as they were, with x-agentsky-relay naming the audit record. 404 connector_not_installed, 403 role_not_granted, 409 connector_misconfigured, 502 service_unreachable. A workspace identity cannot call this; it exchanges itself instead.

## Path parameters

- `id` string, required

## Query parameters

- `sync` 'true'

## Headers

- `Idempotency-Key` string

## Request body

- union: The service's message envelope, or an array of envelopes
  - object
  - object[]

## Response `202`

The service's answer, as it was

- object

## Other responses

- `default`: Error — { error: { code, message } }

## Changes

- **2026-11-02** `e5e8f0229a99`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/agentsky/apis/agentsky-developer-api/changes/workspace-connectors/:id/ingest/messages/post.md)

---

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