API Reference

List inbox messages across connected accounts or within one conversation

Account-level requests default to status=unanswered and windowDays=30, returning latest conversations that need a response. Pass status=all to include answered conversations, or pass conversationId to read full history for one conversation by default. The returned conversationId can be used to queue a direct reply even when no prospectId exists.

GET/v1/accounts/{accountGroupId}/messages

Default inbox filter

Account-level requests default to status=unanswered and a 30-day window, returning latest conversations that need your response. Use status=all for unfiltered account history or pass windowDays from 1 to 30 to narrow the window.

Resolving participants

Use GET /v1/accounts/{accountGroupId}/prospects/by-provider-id/{providerId} with items[].participantProviderId to resolve a conversation participant back to Sonarly prospect records in the same account group.

Integration notes

Permissions

messages:read for listing messages; messages:write for scheduled responses.

Mutation scope

POST /messages/responses creates one-off direct-message or InMail replies only. Campaign-generated messages, comments, and invite notes are changed through campaign workflow-run message updates.

Async

Scheduled responses are queued through Sonarly's outbound scheduler and are not sent synchronously.

Scheduling

Manual and API replies have no recipient cooldown. If no active outbound request already exists for the prospect, Sonarly schedules the next valid business-hours slot while still enforcing fatigue, daily or weekly limits, and account rate limits. Requests fail without queuing content when the first valid slot is more than 72 hours away.

Pagination

List messages uses cursor and limit. Pass nextCursor to continue; hasMore tells you whether another page exists.

Idempotency

Send Idempotency-Key on scheduled-response retries. Same-key, same-body retries return the original scheduled request.

Parameters

accountGroupIdPath

Type: string

Account group ID that scopes the request.

Required

cursorQuery

Type: string

Opaque pagination cursor returned by the previous page.

Optional

limitQuery

Type: number

Maximum number of items to return in this page.

Optional

conversationIdQuery

Type: string

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

Optional

statusQuery

Type: string

Current lifecycle status of the resource.

Optional

windowDaysQuery

Type: integer

Query parameter used to filter or shape window days.

Optional

Request body

This endpoint does not define a request body.

Responses

200

Paginated inbox messages across connected accounts or within one filtered conversation

Schema: MessageListSuccessResponse

400

Request validation failed

Schema: ValidationErrorResponse

401

Invalid or missing API key

Schema: ErrorResponse

403

Missing required permission

Schema: ErrorResponse

429

Rate limit exceeded

Schema: ErrorResponse

500

Internal server error

Schema: ErrorResponse

502

Upstream service error

Schema: ErrorResponse

Response examples

200 Example JSONMessageListSuccessResponse

{
    "success": true,
    "data": {
        "items": [
            {
                "id": "507f1f77bcf86cd799439011",
                "text": "string",
                "sentAt": "string",
                "accountId": "507f1f77bcf86cd799439011",
                "accountType": "string",
                "conversationId": "507f1f77bcf86cd799439011",
                "conversationProviderId": "507f1f77bcf86cd799439011",
                "conversationName": "Avery Stone",
                "participantProviderId": "507f1f77bcf86cd799439011",
                "senderId": "507f1f77bcf86cd799439011",
                "isSender": true,
                "unreadCount": 25,
                "parentMessageId": "507f1f77bcf86cd799439011",
                "attachments": [
                    {
                        "type": "string",
                        "id": "507f1f77bcf86cd799439011",
                        "url": "https://example.com/resource",
                        "fileName": "Avery Stone",
                        "mimeType": "string"
                    }
                ]
            }
        ],
        "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTA0LTI4VDE1OjMwOjAwLjAwMFoifQ",
        "hasMore": 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"
}

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"
}