Update email message status

PUT 
/conversations/messages/email/:emailMessageId/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.write OAuth 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, or replied → implies opened (set to 1 if not already provided and open tracking is enabled) and delivered (set to 1).
• opened → implies delivered (set to 1 if not provided).
• delivered, permanent_fail, or temporary_fail → implies accepted (set to 1 if not provided).

Timestamps

The API automatically records server-side timestamps on first occurrence for delivered, opened, and clicked events. Subsequent updates to these counters do not overwrite the original timestamp.

Request

Version stringrequired

API Version

Available optionsv3

emailMessageId stringrequired

Email Message Id

application/json

application/json

Body

Bodyrequired

eventsobject

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.

recipientsobject[]

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.

statusstringrequired
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.
Available optionspendingscheduledsentdeliveredreadundeliveredconnectedfailedopenedclicked

Example (auto)

{
  "events": {
    "delivered": 1,
    "opened": 1
  },
  "recipients": [
    {
      "emailId": "[email protected]",
      "status": "delivered"
    }
  ],
  "status": "delivered"
}

application/json

Email message status updated successfully

application/json

Schema

Schema

successbooleanrequired

Whether the status update was persisted successfully.

messagestringrequired

Human-readable result message.

Example (auto)

{
  "success": true,
  "message": "Updated email message successfully"
}