Reply to a conversation

POST /v1/inbox/conversations/{conversation_id}/replies

Emails a reply to the conversation's latest inbound message, from the campaign mailbox or the reply address.

Scope: inbox:reply

Access: The key's member must be able to see the conversation in the inbox.

DialEcho sends the reply the way your team's replies from the inbox go out: the recipient, subject and threading come from the conversation, and without html the HTML part is made from text. Recipients, sender, subject, CC, BCC and attachments cannot be set; any field not listed here is rejected. 200 means the mail provider accepted the reply and DialEcho stored it, not that it reached the inbox. It shows in the thread as a manual_reply with external_reply set.

in_reply_to_message_id must be the conversation's latest inbound message, from the feed or the conversation. If a newer one has arrived the reply is refused with 409 conversation_changed: read the conversation again and answer the latest. Each inbound message gets at most one reply through the API, across all your keys; a message your team or the AI agent already answered is 409 already_replied too. A pending AI reply or draft for the message is cancelled when yours is sent; on real-estate conversations a draft waiting for review is refused with 409 draft_requires_review instead.

send_as picks the sender; check the conversation's reply_identities first. campaign_mailbox sends from the mailbox the thread came from. reply_address sends from the campaign's connected reply address; when it is not set up, disconnected or out of capacity the reply is refused with 409 sender_unavailable and never sent from another address.

Idempotency-Key is required and belongs to your API key and this conversation. The same key with the same body returns 200 with the original message and replayed: true and sends nothing, even after the conversation was archived or answered. The same key with a different body is 409 idempotency_conflict. Bodies are compared after text is trimmed and a blank html dropped.

After a timeout or 409 delivery_unknown, retry only with the same Idempotency-Key and body: it reports the outcome and never sends a second email. delivery_unknown means the reply may have gone out, so never send it again under a new key. To change the conversation's state after replying, use PATCH; never resend an email to fix state.

Replies have their own limit on top of the request limit: 20 a minute per API key, in bursts of up to 5. Requests rejected as invalid (422) do not count; every other reply request does, replays included.

Headers

Name	Type	Required	Description
`Idempotency-Key`	`string`	Yes	Identifies this reply for your API key and this conversation. Reusing it with a different body is `409 idempotency_conflict`. 16 to 128 printable ASCII characters, no spaces (a UUID works).

Path parameters

Name	Type	Required	Description
`conversation_id`	`UUID`	Yes	The conversation.

Body

Content type: application/json

Name	Type	Required	Description
`text`	`string`	Yes	The reply as plain text. Leading and trailing whitespace is trimmed, and it must contain more than whitespace. Up to 50,000 characters, counted before trimming.
`html`	`string`	No	An HTML version of the same reply. Blank is the same as leaving it out. Up to 200,000 characters.
`send_as`	`string`	Yes	Which sender to reply from. One of `campaign_mailbox`, `reply_address`.
`in_reply_to_message_id`	`UUID`	Yes	The inbound message you are answering: the conversation's latest inbound message.

Response

Status: 200 OK

The same for a new reply and a replay; replayed tells them apart.

Name	Type	Description
`status`	`string`	Always `sent`. One of `sent`.
`replayed`	`boolean`	`true` when this answers an earlier request with the same `Idempotency-Key`; nothing was sent this time.
`message`	`object`	The reply as stored: `direction` `outbound`, `kind` `manual_reply`, `external_reply` set.
`message.id`	`UUID`	The message. Pass an inbound message's `id` as `in_reply_to_message_id` to answer it.
`message.conversation_id`	`UUID`	Its conversation.
`message.campaign_id`	`UUID`	The conversation's campaign.
`message.domain`	`string`	The conversation's inbox. One of `contact`, `realestate`.
`message.direction`	`string`	`inbound` from the contact, `outbound` to them. One of `inbound`, `outbound`.
`message.kind`	`string \| null`	`human_reply`: a person wrote back. `auto_reply`: an auto-responder, such as an out-of-office. `manual_reply`: sent by your team or through this API. `ai_reply`: sent by the AI email agent. `null` when the message was never classified, as with older messages and `origin_message`. One of `human_reply`, `auto_reply`, `manual_reply`, `ai_reply`.
`message.from_email`	`string \| null`	The sender, following the member's email visibility.
`message.to_emails`	`array of strings`	The recipients. Addresses the member's role hides are left out.
`message.cc_emails`	`array of strings`	The CC recipients, the same way.
`message.subject`	`string \| null`	The subject.
`message.text`	`string \| null`	The plain-text body. `Restricted` when the member's role masks messages.
`message.html`	`string \| null`	The HTML body exactly as stored, or `null` (also when the role masks messages). Sanitize it before you display it and never execute it.
`message.attachments`	`array of objects`	What was attached; there are no download links. Empty when the role masks messages. A detail that is not known is `null`.
`message.attachments.filename`	`string \| null`	The file name.
`message.attachments.content_type`	`string \| null`	The MIME type, for example `application/pdf`.
`message.attachments.size_bytes`	`integer \| null`	The size in bytes.
`message.created_at`	`timestamp \| null`	When DialEcho stored the message (RFC 3339, UTC). The inbound feed is ordered by it.
`message.received_at`	`timestamp \| null`	When the mail provider received an inbound message.
`message.sent_at`	`timestamp \| null`	When an outbound message was sent.
`message.is_synthetic`	`boolean`	`true` only for a conversation's `origin_message`, which is not a stored message.
`message.external_reply`	`object \| null`	Set on replies sent through this API; `null` on every other message.
`message.external_reply.api_key_id`	`UUID \| null`	The API key that sent it.
`message.external_reply.organization_member_id`	`UUID \| null`	The key's team member.
`message.external_reply.automated`	`boolean`	Always `true`: sent by an integration, not typed by a person.
`message.external_reply.in_reply_to_message_id`	`UUID \| null`	The inbound message it answered.

Example request

curl

bash

curl -X POST "https://development.agencydevworks.ai/v1/inbox/conversations/44444444-0000-4000-8000-000000000001/replies" \
  -H "Authorization: Bearer dei_your_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0f0f0f0f-0000-4000-8000-00000000abcd" \
  -d '{
  "text": "Thursday at 2 pm works. Talk then!",
  "html": "<p>Thursday at 2 pm works. Talk then!</p>",
  "send_as": "reply_address",
  "in_reply_to_message_id": "66666666-0000-4000-8000-000000000002"
}'

JavaScript

const response = await fetch("https://development.agencydevworks.ai/v1/inbox/conversations/44444444-0000-4000-8000-000000000001/replies", {
  method: "POST",
  headers: {
    "Authorization": "Bearer dei_your_key",
    "Content-Type": "application/json",
    "Idempotency-Key": "0f0f0f0f-0000-4000-8000-00000000abcd",
  },
  body: JSON.stringify({
    "text": "Thursday at 2 pm works. Talk then!",
    "html": "<p>Thursday at 2 pm works. Talk then!</p>",
    "send_as": "reply_address",
    "in_reply_to_message_id": "66666666-0000-4000-8000-000000000002"
  }),
});
const data = await response.json();

Example response

Status: 200 OK

json

{
  "status": "sent",
  "replayed": false,
  "message": {
    "id": "88888888-0000-4000-8000-000000000001",
    "conversation_id": "44444444-0000-4000-8000-000000000001",
    "campaign_id": "cccccccc-0000-4000-8000-000000000001",
    "domain": "contact",
    "direction": "outbound",
    "kind": "manual_reply",
    "from_email": "jordan@example.com",
    "to_emails": ["pat@example.com"],
    "cc_emails": [],
    "subject": "Re: Your solar quote",
    "text": "Thursday at 2 pm works. Talk then!",
    "html": "<p>Thursday at 2 pm works. Talk then!</p>",
    "attachments": [],
    "created_at": "2026-11-02T16:22:04Z",
    "received_at": null,
    "sent_at": "2026-11-02T16:22:03Z",
    "is_synthetic": false,
    "external_reply": {
      "api_key_id": "abababab-0000-4000-8000-000000000001",
      "organization_member_id": "ffffffff-0000-4000-8000-000000000001",
      "automated": true,
      "in_reply_to_message_id": "66666666-0000-4000-8000-000000000002"
    }
  }
}

Errors

HTTP	Code	When
403	`insufficient_scope`	The key does not have `inbox:reply`. Checked before the body is validated.
404	`not_found`	The conversation does not exist, was deleted, or the key's member cannot see it; or `in_reply_to_message_id` is not a message of this conversation.
409	`idempotency_conflict`	The `Idempotency-Key` was already used on this conversation with a different body. Nothing was sent.
409	`conversation_changed`	`in_reply_to_message_id` is not the latest inbound message any more, or the conversation changed while the reply was prepared. Read it again and answer the latest.
409	`already_replied`	The message was already answered, by your team, the AI agent or another API reply. Do not resend.
409	`reply_in_progress`	Another reply to the conversation is being written or sent right now. `retryable` is `true`: retry shortly with the same `Idempotency-Key`.
409	`delivery_unknown`	The reply may have been sent but the provider did not confirm it. Retry only with the same `Idempotency-Key` and body, never as a new request.
409	`conversation_archived`	The conversation is archived. Restore it with `PATCH` and `{"archived": false}` first.
409	`recipient_suppressed`	The recipient unsubscribed or is suppressed. Do not retry.
409	`non_actionable_inbound`	The message cannot be answered automatically: it is an auto-reply or an opt-out, or the conversation has no recipient address.
409	`sender_unavailable`	The `send_as` sender is not set up, disconnected or out of capacity, or an earlier API reply to this message failed before it was sent and must be reviewed in DialEcho. Nothing was sent.
409	`draft_requires_review`	Real-estate conversations: an AI draft for this message is waiting for review in DialEcho.
413	`payload_too_large`	The body is larger than 1 MB. It was not read and nothing was sent.
422	`invalid_request`	`conversation_id` is not a UUID, the `Idempotency-Key` is missing or malformed, the body is invalid (`error.fields` lists every problem), or `in_reply_to_message_id` is not an inbound message.
429	`rate_limited`	Over the reply limit (20 a minute per key, bursts of 5) or the request limit. Wait the `Retry-After` seconds, then retry with the same `Idempotency-Key`.
503	`dependency_unavailable`	The suppression check, the inbox or the access check was unavailable before anything was sent. Retry with backoff and the same `Idempotency-Key`.

Every endpoint can also answer 401 invalid_api_key, 429 rate_limited and 503 dependency_unavailable. See Errors in the overview.

GET /v1/inbox/inbound-messages · List inbound messages
GET /v1/inbox/conversations/{conversation_id} · Retrieve a conversation
PATCH /v1/inbox/conversations/{conversation_id} · Update a conversation

Reply to a conversation ​

Headers ​

Path parameters ​

Body ​

Response ​

Example request ​

Example response ​

Errors ​

Related endpoints ​