ghl_conversation_update_email_message_status
Update the delivery status, per-recipient outcomes, and event counters for emails sent through a custom conversation provider. Use it to record opens, clicks, failures, and overall message status.
Instructions
Update email message status Update delivery events, per-recipient statuses, and the overall message status for an email sent via a custom conversation provider.
Authorization
Requires the
conversations/message.writeOAuth scope.The calling OAuth app must own the conversation provider that originally sent the email.
Attempts to update emails sent via LC Email or Mailgun will return
403 Forbidden.
Updatable Fields
All request body fields are optional. Pass only what you need to update.
events — Aggregate delivery event counters (integers). Counters are merged into the existing values (not replaced). Setting a counter to 0 is treated as no-op and will not reset the stored value.
recipients — Per-recipient delivery statuses. Each entry maps a recipient email address to a MessageStatus value. Use failReason to capture bounce or rejection details when the status is failed.
status — The overall message status. Accepts any MessageStatus enum value.
Event Inference
The API automatically infers related events to maintain data consistency:
clicked,complained,unsubscribed, orreplied→ impliesopened(set to 1 if not already provided and open tracking is enabled) anddelivered(set to 1).opened→ impliesdelivered(set to 1 if not provided).delivered,permanent_fail, ortemporary_fail→ impliesaccepted(set to 1 if not provided).
Timestamps
The API automatically records server-side timestamps on first oc Endpoint: PUT /conversations/messages/email/{emailMessageId}/status (Version header: v3; source: v3/conversations-v3.json) OAuth scopes: conversations/message.write
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"emailMessageId": "<emailMessageId>",
"body": "<body>"
},
"name": "ghl_conversation_update_email_message_status"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| body | Yes | Request body to update the delivery status of an email message. `status` is required. `events` and `recipients` are optional and may be included together with `status`. - Use `events` to report aggregate delivery metrics (delivered count, open count, etc.). - Use `recipients` to track per-recipient delivery outcomes for multi-recipient emails. - Use `status` to set the overall message status. Multiple calls are additive — event counters are merged, recipient statuses are upserted, and the message status is overwritten. | |
| emailMessageId | Yes | Email Message Id |