HighLevel: Update email message status

← Conversations operations · Get started

Operation gohighlevel.update_email_message_status

Provider route: PUT /conversations/messages/email/{id}/status. Alter supplies the connection’s credentials and routing.

Call through Alter

Install @alter-ai/sdk @alter-ai/gohighlevel with npm, or alter-sdk-gohighlevel with pip. Supply your connected customer’s grant ID and the arguments described below.

import { App } from "@alter-ai/sdk";
import { HighLevelIntegration } from "@alter-ai/gohighlevel";

async function execute(input: Parameters<HighLevelIntegration["conversations"]["updateEmailMessageStatus"]>[0]) {
  const app = new App({ apiKey: process.env.ALTER_API_KEY! });
  try {
    const provider = new HighLevelIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! });
    const call = await provider.conversations.updateEmailMessageStatus(input);
    const result = await call.wait();
    return result.bodyJson();
  } finally {
    await app.close();
  }
}

import os
from alter_sdk import App
from alter_sdk_gohighlevel import HighLevelIntegration

async def execute(arguments):
    async with App(api_key=os.environ["ALTER_API_KEY"]) as app:
        provider = HighLevelIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]})
        call = await provider.conversations.update_email_message_status(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
path	object	Required within parent	Additional keys: not allowed
path.id	string	Required within parent
body	Model	Required within parent	Expand Update email message status — request body — body

Referenced models: Update email message status — request body — body

Response

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

Field	Type	Presence	Description and constraints
$	Model	Root	Expand Update email message status — response body

Referenced models: Update email message status — response body

Schemas

Update email message status — response body

Field	Type	Presence	Description and constraints
$	object	Root	Response returned after successfully updating the email message status.
message	string	Required within parent	Human-readable result message.
success	boolean	Required within parent	Whether the status update was persisted successfully.

Update email message status — request body — body

Field	Type	Presence	Description and constraints
$	object	Root	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.
events	JSON	Optional	Aggregate delivery event counters. Counters are merged into existing values. The API automatically infers related events (e.g., reporting `clicked` will also set `opened` and `delivered` if not already present). See the endpoint description for the full inference rules.
events (allOf 1)	Model	All variants apply	Expand Update email message status — request body — body events accepted, clicked, complained, delivered, failed, opened, rejected, replied, stored, unsubscribed
recipients	array	Optional	Per-recipient delivery statuses. Each entry maps a recipient email address to a delivery status. Entries are upserted — if a recipient already has a status, it will be overwritten with the new value.
recipients[]	Model	Each item	Expand Update email message status — request body — body recipients item
status	string	Required within parent	The overall status of the email message. Required on every request. For emails with multiple recipients, consider using the `recipients` array for granular tracking and this field for the aggregate status. One of: pending, scheduled, sent, delivered, read, undelivered, connected, failed, opened, clicked

Referenced models: Update email message status — request body — body events accepted, clicked, complained, delivered, failed, opened, rejected, replied, stored, unsubscribed, Update email message status — request body — body recipients item

Update email message status — request body — body events accepted, clicked, complained, delivered, failed, opened, rejected, replied, stored, unsubscribed

Field	Type	Presence	Description and constraints
$	object	Root	Aggregate delivery event counters for the email message. Values are merged into existing stored counters (additive update, not replacement). A value of `0` is treated as a no-op and will not reset the stored counter. Only include fields you want to update. Provider-specific counters such as `permanent_fail`, `temporary_fail`, and `esp_isp_block` may be sent using those snake_case keys. Additional keys: see wildcard field
accepted	integer	Optional	Number of messages accepted by the receiving mail server for delivery. Automatically inferred (set to 1) when `delivered`, `permanent_fail`, or `temporary_fail` events are reported.
clicked	integer	Optional	Number of link click events within the email body. Triggers automatic inference of both `opened` and `delivered`.
complained	integer	Optional	Number of spam complaint events (e.g., recipient marked the email as spam). Triggers automatic inference of `opened` and `delivered`.
delivered	integer	Optional	Number of successful deliveries — the recipient mail server accepted the message. Automatically inferred (set to 1) when `opened`, `clicked`, `complained`, `unsubscribed`, or `replied` events are reported.
failed	integer	Optional	Total number of delivery failures (includes both permanent and temporary). For more granular failure tracking, use `permanent_fail` and `temporary_fail` instead.
opened	integer	Optional	Number of unique open events (typically tracked via a tracking pixel). Automatically inferred (set to 1) when `clicked`, `complained`, `unsubscribed`, or `replied` events are reported, provided open tracking is enabled on the email.
rejected	integer	Optional	Number of messages rejected outright by the receiving mail server (before acceptance).
replied	integer	Optional	Number of reply events. Triggers automatic inference of both `opened` (if open tracking is enabled) and `delivered`.
stored	integer	Optional	Number of messages stored by the email service provider (ESP-specific event).
unsubscribed	integer	Optional	Number of unsubscribe events triggered by the recipient. Triggers automatic inference of `opened` and `delivered`.
$.*	integer	Additional keys	Additional provider event counter (merged into stored values).

Update email message status — request body — body recipients item

Field	Type	Presence	Description and constraints
$	object	Root	Delivery status for an individual recipient of a multi-recipient email. Each entry is keyed by the recipient's email address and tracks their specific delivery outcome independently from the aggregate event counters.
emailId	string	Required within parent	The recipient's email address. This is used as the key to store and update the per-recipient status. Must match one of the original recipients of the email.
failReason	string	Optional	Human-readable reason for the delivery failure. Only applicable when `status` is `failed`. Examples: "Mailbox not found", "Quota exceeded", "Blocked by recipient server".
status	string	Required within parent	The delivery status for this specific recipient. Common values for status updates: `delivered` (successfully delivered), `failed` (delivery failed — provide `failReason`), `opened` (recipient opened the email), `clicked` (recipient clicked a link). One of: pending, scheduled, sent, delivered, read, undelivered, connected, failed, opened, clicked

Policy, approvals and errors

SDK function policy ID: gohighlevel.update_email_message_status. Catalog operation: update-email-message-status. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.

Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.

Required provider scopes: ["conversations/message.write"]

Pinned headers: {"Version": "v3"}

Official provider source