Message Manager Setup

Retrieve individual message records, update read status, and manually create inbound or outbound message entries through the GHL MCP server. This tool gives you fine-grained control over message data, letting you build read receipts, sync external messaging systems, and audit communication history programmatically.

Prerequisites

Before using the message management endpoints, confirm the following:

• A GoHighLevel sub-account with active conversations containing messages
• A Private Integration Token (PIT) with the conversations scope enabled
• At least one message ID to work with (retrieve these from conversation search or send operations)
• Your location ID for creating manual message records

If you do not have existing messages, send a test SMS or email first using SMS Operations or Email Send to generate message records.

Set Up Authentication

Create a PIT from Settings > Integrations > Private Integrations in your sub-account. Click Create New, name it “MCP Message Manager,” and enable the conversations scope. Copy the token and store it securely in your MCP client configuration.

Include these headers on every request: Authorization: Bearer YOUR_PIT_TOKEN, Content-Type: application/json, and Version: 2021-07-28. All message management endpoints use the same authentication method.

Make Your First Call

Start by retrieving a single message with GET /messages/{id}. Pass the message ID you obtained from a previous send operation or conversation search. This returns the full message record including content, channel type, timestamps, and delivery status.

To update read status, call PUT /messages/{id}/status with a body specifying the new status. Use this to mark messages as read or unread programmatically, which is useful for building custom inbox interfaces or notification systems.

To create an inbound message record, use POST /conversations/messages/inbound with the following fields:

• type — the channel type (SMS, Email, etc.)
• conversationId — the target conversation thread
• message — the message content
• contactId — the sender contact’s ID

To create an outbound message record, use POST /conversations/messages/outbound with the same structure. This logs a message as if it was sent from the location without actually dispatching it, which is useful for syncing external communications into GHL.

Handle the Response

Message retrieval returns a JSON object with the id, body, type, direction (inbound or outbound), status, dateAdded, and conversationId. The status field shows delivery state: "sent", "delivered", "read", or "failed".

For status updates, the response confirms the new status value. If the message ID is invalid, you receive a 404 error.

Manually created inbound and outbound records return the full message object with an auto-generated id. These messages appear in the conversation timeline and can trigger workflows if configured. Note that outbound records created this way are logged only and do not actually send a message to the contact.

Test Your Setup

Validate each operation in sequence:

• Retrieve: Call GET /messages/{id} with a known message ID and confirm the response contains the expected content, channel type, and timestamps
• Update status: Mark a message as read using PUT /messages/{id}/status and verify the change reflects in the GHL conversations inbox
• Create inbound: Post a test inbound record and confirm it appears in the conversation timeline as an incoming message
• Create outbound: Post a test outbound record and verify it shows as a sent message in the thread

See the full Message Manager guide for bulk operations and advanced filtering. For uploading files to attach to messages, use Attachment Handler.