API Reference

Queue a scheduled message response

Queues a prospect response through Sonarly's outbound scheduler instead of sending synchronously. Use `direct_message` for existing connected chats and `inmail` with `subject` for eligible new conversations.

POST/v1/accounts/{accountGroupId}/messages/responses

Channel behavior

Use direct_message when the prospect is connected and has an existing chat. Use inmail with a subject for eligible new conversations.

Safe retries

Send an Idempotency-Key header when retrying. Same-key, same-body retries return the original scheduled request; conflicting retries return 409 IDEMPOTENCY_CONFLICT.

Integration notes

Required API permission

messages:write.

Prerequisites

integration_api_key, account_group_access.

Idempotency

send a stable Idempotency-Key header when retrying this request.

Parameters

accountGroupIdPath

Type: string

Account group ID that scopes the request.

Required

Request body

Required

Optional

Content types

application/json

Schema

object

Fields

prospectId

Type: string

Sonarly prospect ID scoped to the account group.

Required

message

Type: string

Message body to queue or send.

Required

channel

Type: direct_message | inmail

Delivery channel for the response, such as direct_message or inmail.

Optional

conversationId

Type: string

Existing conversation ID used when responding in a direct message thread.

Optional

subject

Type: string

InMail subject line. Required when channel is inmail.

Optional

Responses

202

Queued or scheduled outbound message response

Schema: ScheduledMessageResponseSuccessResponse

400

Request validation failed

Schema: ValidationErrorResponse

401

Invalid or missing API key

Schema: ErrorResponse

403

Missing required permission

Schema: ErrorResponse

409

Conflict — resource is in a state that prevents this operation

Schema: ErrorResponse

422

Request validation failed

Schema: ValidationErrorResponse

429

Rate limit exceeded

Schema: ErrorResponse

500

Internal server error

Schema: ErrorResponse

502

Upstream service error

Schema: ErrorResponse

Response examples

202 Example JSONScheduledMessageResponseSuccessResponse

{
    "success": true,
    "data": {
        "id": "507f1f77bcf86cd799439011",
        "status": "queued",
        "scheduledAt": "2026-04-28T15:30:00.000Z",
        "sentAt": "2026-04-28T15:30:00.000Z",
        "channel": "direct_message",
        "conversationId": "507f1f77bcf86cd799439011",
        "messageId": "507f1f77bcf86cd799439011",
        "idempotencyKey": "string",
        "deferred": true
    },
    "error": null,
    "traceId": "507f1f77bcf86cd799439011"
}

400 Example JSONValidationErrorResponse

{
    "success": false,
    "data": null,
    "error": {
        "code": "VALIDATION_ERROR",
        "message": "Thanks for the context. I can send over details this afternoon.",
        "details": "string"
    },
    "traceId": "507f1f77bcf86cd799439011"
}

401 Example JSONErrorResponse

{
    "success": false,
    "data": null,
    "error": {
        "code": "string",
        "message": "Thanks for the context. I can send over details this afternoon.",
        "details": "string"
    },
    "traceId": "507f1f77bcf86cd799439011"
}

403 Example JSONErrorResponse

{
    "success": false,
    "data": null,
    "error": {
        "code": "string",
        "message": "Thanks for the context. I can send over details this afternoon.",
        "details": "string"
    },
    "traceId": "507f1f77bcf86cd799439011"
}

409 Example JSONErrorResponse

{
    "success": false,
    "data": null,
    "error": {
        "code": "string",
        "message": "Thanks for the context. I can send over details this afternoon.",
        "details": "string"
    },
    "traceId": "507f1f77bcf86cd799439011"
}

422 Example JSONValidationErrorResponse

{
    "success": false,
    "data": null,
    "error": {
        "code": "VALIDATION_ERROR",
        "message": "Thanks for the context. I can send over details this afternoon.",
        "details": "string"
    },
    "traceId": "507f1f77bcf86cd799439011"
}

429 Example JSONErrorResponse

{
    "success": false,
    "data": null,
    "error": {
        "code": "string",
        "message": "Thanks for the context. I can send over details this afternoon.",
        "details": "string"
    },
    "traceId": "507f1f77bcf86cd799439011"
}

500 Example JSONErrorResponse

{
    "success": false,
    "data": null,
    "error": {
        "code": "string",
        "message": "Thanks for the context. I can send over details this afternoon.",
        "details": "string"
    },
    "traceId": "507f1f77bcf86cd799439011"
}

502 Example JSONErrorResponse

{
    "success": false,
    "data": null,
    "error": {
        "code": "string",
        "message": "Thanks for the context. I can send over details this afternoon.",
        "details": "string"
    },
    "traceId": "507f1f77bcf86cd799439011"
}