Skip to main content
Version: 2023-02-21

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​

Responses​

Email message status updated successfully